Centralize and standardize callback usage (#291)

* Centralize and standardize callback usage

* Fix tests

* Fix tests

Author: bachya

docs/api.rst

@@ -77,6 +77,9 @@ Systems
 Utilities
 ---------
 
+.. automodule:: simplipy.util
+   :members:
+
 ``auth``
 ********
 

docs/websocket.rst

@@ -33,14 +33,14 @@ Disconnecting
 Responding to Events
 --------------------
 
-Users respond to events by defining listeners (synchronous functions *or* coroutines).
+Users respond to events by defining callbacks (synchronous functions *or* coroutines).
 The following events exist:
 
 * ``connect``: occurs when the websocket connection is established
 * ``disconnect``: occurs when the websocket connection is terminated
 * ``event``: occurs when any data is transmitted from the SimpliSafe™ cloud
 
-Note that you can register as many listeners as you'd like.
+Note that you can register as many callbacks as you'd like.
 
 ``connect``
 ***********
@@ -54,10 +54,10 @@ Note that you can register as many listeners as you'd like.
     def connect_handler():
         print("I connected to the websocket")
 
-    remove_1 = simplisafe.websocket.add_connect_listener(async_connect_handler)
-    remove_2 = simplisafe.websocket.add_connect_listener(connect_handler)
+    remove_1 = simplisafe.websocket.add_connect_callback(async_connect_handler)
+    remove_2 = simplisafe.websocket.add_connect_callback(connect_handler)
 
-    # remove_1 and remove_2 are functions that, when called, remove the listener.
+    # remove_1 and remove_2 are functions that, when called, remove the callback.
 
 ``disconnect``
 **************
@@ -71,10 +71,10 @@ Note that you can register as many listeners as you'd like.
     def connect_handler():
         print("I disconnected from the websocket")
 
-    remove_1 = simplisafe.websocket.add_disconnect_listener(async_connect_handler)
-    remove_2 = simplisafe.websocket.add_disconnect_listener(connect_handler)
+    remove_1 = simplisafe.websocket.add_disconnect_callback(async_connect_handler)
+    remove_2 = simplisafe.websocket.add_disconnect_callback(connect_handler)
 
-    # remove_1 and remove_2 are functions that, when called, remove the listener.
+    # remove_1 and remove_2 are functions that, when called, remove the callback.
 
 ``event``
 *********
@@ -88,15 +88,15 @@ Note that you can register as many listeners as you'd like.
     def connect_handler():
         print(f"I received a SimpliSafe™ event: {event}")
 
-    remove_1 = simplisafe.websocket.add_event_listener(async_connect_handler)
-    remove_2 = simplisafe.websocket.add_event_listener(connect_handler)
+    remove_1 = simplisafe.websocket.add_event_callback(async_connect_handler)
+    remove_2 = simplisafe.websocket.add_event_callback(connect_handler)
 
-    # remove_1 and remove_2 are functions that, when called, remove the listener.
+    # remove_1 and remove_2 are functions that, when called, remove the callback.
 
 Response Format
 ===============
 
-The ``event`` argument provided to event listeners is a
+The ``event`` argument provided to event callbacks is a
 :meth:`simplipy.websocket.WebsocketEvent` object, which comes with several properties:
 
 * ``changed_by``: the PIN that caused the event (in the case of arming/disarming/etc.)

simplipy/api.py

@@ -19,6 +19,7 @@
 )
 from simplipy.system.v2 import SystemV2
 from simplipy.system.v3 import SystemV3
+from simplipy.util import schedule_callback
 from simplipy.util.auth import (
     AUTH_URL_BASE,
     AUTH_URL_HOSTNAME,
@@ -65,7 +66,7 @@ def __init__(
         request_retries: int = DEFAULT_REQUEST_RETRIES,
     ) -> None:
         """Initialize."""
-        self._refresh_token_listeners: list[Callable[..., None]] = []
+        self._refresh_token_callbacks: list[Callable[..., None]] = []
         self.session: ClientSession = session
 
         # These will get filled in after initial authentication:
@@ -215,8 +216,8 @@ async def _async_refresh_access_token(self) -> None:
         self.access_token = token_resp["access_token"]
         self.refresh_token = token_resp["refresh_token"]
 
-        for callback in self._refresh_token_listeners:
-            callback(self.refresh_token)
+        for callback in self._refresh_token_callbacks:
+            schedule_callback(callback, self.refresh_token)
 
     async def _async_request(
         self, method: str, endpoint: str, url_base: str = API_URL_BASE, **kwargs: Any
@@ -261,21 +262,21 @@ async def _async_request(
 
         return data
 
-    def add_refresh_token_listener(
+    def add_refresh_token_callback(
         self, callback: Callable[..., None]
     ) -> Callable[..., None]:
-        """Add a listener that should be triggered when tokens are refreshed.
+        """Add a callback that should be triggered when tokens are refreshed.
 
         Note that callbacks should expect to receive a refresh token as a parameter.
 
         :param callback: The method to call after receiving an event.
         :type callback: ``Callable[..., None]``
         """
-        self._refresh_token_listeners.append(callback)
+        self._refresh_token_callbacks.append(callback)
 
         def remove() -> None:
             """Remove the callback."""
-            self._refresh_token_listeners.remove(callback)
+            self._refresh_token_callbacks.remove(callback)
 
         return remove
 

simplipy/util/__init__.py

@@ -1 +1,12 @@
 """Define utility modules."""
+import asyncio
+from typing import Any, Callable
+
+
+def schedule_callback(callback: Callable[..., Any], *args: Any) -> None:
+    """Schedule a callback to be called."""
+    if asyncio.iscoroutinefunction(callback):
+        asyncio.create_task(callback(*args))
+    else:
+        loop = asyncio.get_running_loop()
+        loop.call_soon(callback, *args)

simplipy/websocket.py

@@ -22,6 +22,7 @@
     InvalidMessageError,
     NotConnectedError,
 )
+from simplipy.util import schedule_callback
 from simplipy.util.dt import utc_from_timestamp
 
 if TYPE_CHECKING:
@@ -116,11 +117,7 @@ def __init__(
     def _on_expire(self) -> None:
         """Log and act when the watchdog expires."""
         LOGGER.info("Websocket watchdog expired")
-
-        if asyncio.iscoroutinefunction(self._action):
-            asyncio.create_task(self._action())
-        else:
-            self._loop.call_soon(self._action())
+        schedule_callback(self._action)
 
     def cancel(self) -> None:
         """Cancel the watchdog."""
@@ -213,9 +210,9 @@ class WebsocketClient:
     def __init__(self, api: API) -> None:
         """Initialize."""
         self._api = api
-        self._connect_listeners: list[Callable[..., None]] = []
-        self._disconnect_listeners: list[Callable[..., None]] = []
-        self._event_listeners: list[Callable[..., None]] = []
+        self._connect_callbacks: list[Callable[..., None]] = []
+        self._disconnect_callbacks: list[Callable[..., None]] = []
+        self._event_callbacks: list[Callable[..., None]] = []
         self._loop = asyncio.get_running_loop()
         self._watchdog = Watchdog(self.async_reconnect)
 
@@ -228,15 +225,15 @@ def connected(self) -> bool:
         return self._client is not None and not self._client.closed
 
     @staticmethod
-    def _add_listener(
-        listener_list: list, callback: Callable[..., Any]
+    def _add_callback(
+        callback_list: list, callback: Callable[..., Any]
     ) -> Callable[..., None]:
-        """Add a listener callback to a particular list."""
-        listener_list.append(callback)
+        """Add a callback callback to a particular list."""
+        callback_list.append(callback)
 
         def remove() -> None:
             """Remove the callback."""
-            listener_list.remove(callback)
+            callback_list.remove(callback)
 
         return remove
 
@@ -283,44 +280,37 @@ def _parse_message(self, message: dict[str, Any]) -> None:
         """Parse an incoming message."""
         if message["type"] == "com.simplisafe.event.standard":
             event = websocket_event_from_payload(message)
-            for listener in self._event_listeners:
-                self._schedule_listener_call(listener, event)
-
-    def _schedule_listener_call(self, listener: Callable[..., Any], *args: Any) -> None:
-        """Schedule a listener to be called."""
-        if asyncio.iscoroutinefunction(listener):
-            asyncio.create_task(listener(*args))
-        else:
-            self._loop.call_soon(listener, *args)
+            for callback in self._event_callbacks:
+                schedule_callback(callback, event)
 
-    def add_connect_listener(self, callback: Callable[..., Any]) -> Callable[..., None]:
-        """Add a listener callback to be called after connecting.
+    def add_connect_callback(self, callback: Callable[..., Any]) -> Callable[..., None]:
+        """Add a callback callback to be called after connecting.
 
         :param callback: The method to call after connecting
         :type callback: ``Callable[..., None]``
         """
-        return self._add_listener(self._connect_listeners, callback)
+        return self._add_callback(self._connect_callbacks, callback)
 
-    def add_disconnect_listener(
+    def add_disconnect_callback(
         self, callback: Callable[..., Any]
     ) -> Callable[..., None]:
-        """Add a listener callback to be called after disconnecting.
+        """Add a callback callback to be called after disconnecting.
 
         :param callback: The method to call after disconnecting
         :type callback: ``Callable[..., None]``
         """
-        return self._add_listener(self._disconnect_listeners, callback)
+        return self._add_callback(self._disconnect_callbacks, callback)
 
-    def add_event_listener(self, callback: Callable[..., Any]) -> Callable[..., None]:
-        """Add a listener callback to be called upon receiving an event.
+    def add_event_callback(self, callback: Callable[..., Any]) -> Callable[..., None]:
+        """Add a callback callback to be called upon receiving an event.
 
         Note that callbacks should expect to receive a WebsocketEvent object as a
         parameter.
 
         :param callback: The method to call after receiving an event.
         :type callback: ``Callable[..., None]``
         """
-        return self._add_listener(self._event_listeners, callback)
+        return self._add_callback(self._event_callbacks, callback)
 
     async def async_connect(self) -> None:
         """Connect to the websocket server."""
@@ -333,8 +323,8 @@ async def async_connect(self) -> None:
 
         LOGGER.info("Connected to websocket server")
 
-        for listener in self._connect_listeners:
-            self._schedule_listener_call(listener)
+        for callback in self._connect_callbacks:
+            schedule_callback(callback)
 
         self._watchdog.trigger()
 
@@ -346,8 +336,8 @@ async def async_disconnect(self) -> None:
 
         LOGGER.info("Disconnected from websocket server")
 
-        for listener in self._disconnect_listeners:
-            self._schedule_listener_call(listener)
+        for callback in self._disconnect_callbacks:
+            schedule_callback(callback)
 
     async def async_listen(self) -> None:
         """Start listening to the websocket server."""
@@ -384,8 +374,8 @@ async def async_listen(self) -> None:
         finally:
             LOGGER.debug("Listen completed; cleaning up")
 
-            for listener in self._disconnect_listeners:
-                self._schedule_listener_call(listener)
+            for callback in self._disconnect_callbacks:
+                schedule_callback(callback)
 
     async def async_reconnect(self) -> None:
         """Reconnect (and re-listen, if appropriate) to the websocket."""

tests/test_api.py

@@ -1,5 +1,6 @@
 """Define tests for the System object."""
 # pylint: disable=protected-access,too-many-arguments
+import asyncio
 from datetime import datetime
 from unittest.mock import Mock
 
@@ -205,18 +206,14 @@ async def test_client_async_from_refresh_token(
 
 
 @pytest.mark.asyncio
-async def test_refresh_token_listener_callback(
+async def test_refresh_token_callback(
     api_token_response,
     aresponses,
-    caplog,
     server,
     v2_settings_response,
     v2_subscriptions_response,
 ):
-    """Test that listener callbacks are executed correctly."""
-    import logging
-
-    caplog.set_level(logging.DEBUG)
+    """Test that callback callbacks are executed correctly."""
     server.add(
         "api.simplisafe.com",
         f"/v1/users/{TEST_SUBSCRIPTION_ID}/subscriptions",
@@ -254,8 +251,8 @@ async def test_refresh_token_listener_callback(
         response=aiohttp.web_response.json_response(v2_settings_response, status=200),
     )
 
-    mock_listener_1 = Mock()
-    mock_listener_2 = Mock()
+    mock_callback_1 = Mock()
+    mock_callback_2 = Mock()
 
     async with aiohttp.ClientSession() as session:
         simplisafe = await API.async_from_auth(
@@ -265,18 +262,19 @@ async def test_refresh_token_listener_callback(
         # Manually set the expiration datetime to force a refresh token flow:
         simplisafe._access_token_expire_dt = datetime.utcnow()
 
-        # We'll hang onto one listener callback:
-        simplisafe.add_refresh_token_listener(mock_listener_1)
-        assert mock_listener_1.call_count == 0
+        # We'll hang onto one callback callback:
+        simplisafe.add_refresh_token_callback(mock_callback_1)
+        assert mock_callback_1.call_count == 0
 
         # ..and delete the a second one before ever using it:
-        remove = simplisafe.add_refresh_token_listener(mock_listener_2)
+        remove = simplisafe.add_refresh_token_callback(mock_callback_2)
         remove()
 
         await simplisafe.async_get_systems()
-        mock_listener_1.assert_called_once_with("aabbcc11")
-        assert mock_listener_1.call_count == 1
-        assert mock_listener_2.call_count == 0
+        await asyncio.sleep(1)
+        mock_callback_1.assert_called_once_with("aabbcc11")
+        assert mock_callback_1.call_count == 1
+        assert mock_callback_2.call_count == 0
 
 
 @pytest.mark.asyncio