add ping_interval and ping_timeout params

Author: tmunzer-AIDE

README.md

@@ -31,8 +31,9 @@ A comprehensive Python package to interact with the Mist Cloud APIs, built from
     - [Pagination](#pagination-support)
     - [Examples](#examples)
 - [WebSocket Streaming](#websocket-streaming)
-    - [Available Channels](#available-channels)
+    - [Connection Parameters](#connection-parameters)
     - [Callbacks](#callbacks)
+    - [Available Channels](#available-channels)
     - [Usage Patterns](#usage-patterns)
 - [Development](#development-and-testing)
 - [Contributing](#contributing)
@@ -482,6 +483,34 @@ events = mistapi.api.v1.orgs.clients.searchOrgClientsEvents(
 
 The package provides a WebSocket client for real-time event streaming from the Mist API (`wss://{host}/api-ws/v1/stream`). Authentication is handled automatically using the same session credentials (API token or login/password).
 
+### Connection Parameters
+
+All channel classes accept the following optional keyword arguments to control the WebSocket keep-alive behaviour:
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `ping_interval` | `int` | `30` | Seconds between automatic ping frames. Set to `0` to disable pings. |
+| `ping_timeout` | `int` | `10` | Seconds to wait for a pong response before treating the connection as dead. |
+
+```python
+ws = mistapi.websockets.sites.SiteDeviceStatsEvents(
+    apisession,
+    site_id="<site_id>",
+    ping_interval=60,   # ping every 60 s
+    ping_timeout=20,    # wait up to 20 s for pong
+)
+ws.connect()
+```
+
+### Callbacks
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `ws.on_open(cb)` | `cb()` | Called when the connection is established |
+| `ws.on_message(cb)` | `cb(data: dict)` | Called for every incoming message |
+| `ws.on_error(cb)` | `cb(error: Exception)` | Called on WebSocket errors |
+| `ws.on_close(cb)` | `cb(status_code: int, msg: str)` | Called when the connection closes |
+
 ### Available Channels
 
 #### Organization Channels
@@ -512,15 +541,6 @@ The package provides a WebSocket client for real-time event streaming from the M
 | `mistapi.websockets.location.LocationUnconnectedClientsEvents` | `/sites/{site_id}/stats/maps/{map_id}/unconnected_clients` | Real-time unconnected clients location events |
 | `mistapi.websockets.location.LocationDiscoveredBleAssetsEvents` | `/sites/{site_id}/stats/maps/{map_id}/discovered_assets` | Real-time discovered BLE assets location events |
 
-### Callbacks
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `ws.on_open(cb)` | `cb()` | Called when the connection is established |
-| `ws.on_message(cb)` | `cb(data: dict)` | Called for every incoming message |
-| `ws.on_error(cb)` | `cb(error: Exception)` | Called on WebSocket errors |
-| `ws.on_close(cb)` | `cb(status_code: int, msg: str)` | Called when the connection closes |
-
 ### Usage Patterns
 
 #### Callback style (recommended)

src/mistapi/websockets/__ws_client.py

@@ -36,9 +36,17 @@ class _MistWebsocket:
     - Login/password sessions pass the requests Session cookies.
     """
 
-    def __init__(self, mist_session: "APISession", channel: str) -> None:
+    def __init__(
+        self,
+        mist_session: "APISession",
+        channel: str,
+        ping_interval: int = 30,
+        ping_timeout: int = 10,
+    ) -> None:
         self._mist_session = mist_session
         self._channel = channel
+        self._ping_interval = ping_interval
+        self._ping_timeout = ping_timeout
         self._ws: websocket.WebSocketApp | None = None
         self._thread: threading.Thread | None = None
         self._queue: queue.Queue[dict | None] = queue.Queue()
@@ -147,7 +155,7 @@ def connect(self, run_in_background: bool = True) -> None:
     def _run_forever_safe(self) -> None:
         if self._ws:
             try:
-                self._ws.run_forever(ping_interval=30, ping_timeout=10)
+                self._ws.run_forever(ping_interval=self._ping_interval, ping_timeout=self._ping_timeout)
             except Exception as exc:
                 self._handle_error(self._ws, exc)
                 self._handle_close(self._ws, -1, str(exc))

src/mistapi/websockets/location.py

@@ -54,9 +54,9 @@ class LocationBleAssetsEvents(_MistWebsocket):
             time.sleep(60)
     """
 
-    def __init__(self, mist_session: APISession, site_id: str, map_id: str) -> None:
+    def __init__(self, mist_session: APISession, site_id: str, map_id: str, **kwargs) -> None:
         super().__init__(
-            mist_session, channel=f"/sites/{site_id}/stats/maps/{map_id}/assets"
+            mist_session, channel=f"/sites/{site_id}/stats/maps/{map_id}/assets", **kwargs
         )
 
 
@@ -99,10 +99,11 @@ class LocationConnectedClientsEvents(_MistWebsocket):
             time.sleep(60)
     """
 
-    def __init__(self, mist_session: APISession, site_id: str, map_id: str) -> None:
+    def __init__(self, mist_session: APISession, site_id: str, map_id: str, **kwargs) -> None:
         super().__init__(
             mist_session,
             channel=f"/sites/{site_id}/stats/maps/{map_id}/clients",
+            **kwargs,
         )
 
 
@@ -145,10 +146,11 @@ class LocationSdkClientsEvents(_MistWebsocket):
             time.sleep(60)
     """
 
-    def __init__(self, mist_session: APISession, site_id: str, map_id: str) -> None:
+    def __init__(self, mist_session: APISession, site_id: str, map_id: str, **kwargs) -> None:
         super().__init__(
             mist_session,
             channel=f"/sites/{site_id}/stats/maps/{map_id}/sdkclients",
+            **kwargs,
         )
 
 
@@ -191,10 +193,11 @@ class LocationUnconnectedClientsEvents(_MistWebsocket):
             time.sleep(60)
     """
 
-    def __init__(self, mist_session: APISession, site_id: str, map_id: str) -> None:
+    def __init__(self, mist_session: APISession, site_id: str, map_id: str, **kwargs) -> None:
         super().__init__(
             mist_session,
             channel=f"/sites/{site_id}/stats/maps/{map_id}/unconnected_clients",
+            **kwargs,
         )
 
 
@@ -237,8 +240,9 @@ class LocationDiscoveredBleAssetsEvents(_MistWebsocket):
             time.sleep(60)
     """
 
-    def __init__(self, mist_session: APISession, site_id: str, map_id: str) -> None:
+    def __init__(self, mist_session: APISession, site_id: str, map_id: str, **kwargs) -> None:
         super().__init__(
             mist_session,
             channel=f"/sites/{site_id}/stats/maps/{map_id}/discovered_assets",
+            **kwargs,
         )

src/mistapi/websockets/orgs.py

@@ -52,8 +52,8 @@ class OrgInsightsEvents(_MistWebsocket):
             time.sleep(60)
     """
 
-    def __init__(self, mist_session: APISession, org_id: str) -> None:
-        super().__init__(mist_session, channel=f"/orgs/{org_id}/insights/summary")
+    def __init__(self, mist_session: APISession, org_id: str, **kwargs) -> None:
+        super().__init__(mist_session, channel=f"/orgs/{org_id}/insights/summary", **kwargs)
 
 
 class OrgMxEdgesStatsEvents(_MistWebsocket):
@@ -93,8 +93,8 @@ class OrgMxEdgesStatsEvents(_MistWebsocket):
             time.sleep(60)
     """
 
-    def __init__(self, mist_session: APISession, org_id: str) -> None:
-        super().__init__(mist_session, channel=f"/orgs/{org_id}/stats/mxedges")
+    def __init__(self, mist_session: APISession, org_id: str, **kwargs) -> None:
+        super().__init__(mist_session, channel=f"/orgs/{org_id}/stats/mxedges", **kwargs)
 
 
 class OrgMxEdgesUpgradesEvents(_MistWebsocket):
@@ -134,5 +134,5 @@ class OrgMxEdgesUpgradesEvents(_MistWebsocket):
             time.sleep(60)
     """
 
-    def __init__(self, mist_session: APISession, org_id: str) -> None:
-        super().__init__(mist_session, channel=f"/orgs/{org_id}/mxedges")
+    def __init__(self, mist_session: APISession, org_id: str, **kwargs) -> None:
+        super().__init__(mist_session, channel=f"/orgs/{org_id}/mxedges", **kwargs)

src/mistapi/websockets/sites.py

@@ -52,8 +52,8 @@ class SiteClientsStatsEvents(_MistWebsocket):
             time.sleep(60)
     """
 
-    def __init__(self, mist_session: APISession, site_id: str) -> None:
-        super().__init__(mist_session, channel=f"/sites/{site_id}/stats/clients")
+    def __init__(self, mist_session: APISession, site_id: str, **kwargs) -> None:
+        super().__init__(mist_session, channel=f"/sites/{site_id}/stats/clients", **kwargs)
 
 
 class SiteDeviceCmdEvents(_MistWebsocket):
@@ -101,9 +101,9 @@ class SiteDeviceCmdEvents(_MistWebsocket):
             time.sleep(60)
     """
 
-    def __init__(self, mist_session: APISession, site_id: str, device_id: str) -> None:
+    def __init__(self, mist_session: APISession, site_id: str, device_id: str, **kwargs) -> None:
         super().__init__(
-            mist_session, channel=f"/sites/{site_id}/devices/{device_id}/cmd"
+            mist_session, channel=f"/sites/{site_id}/devices/{device_id}/cmd", **kwargs
         )
 
 
@@ -144,8 +144,8 @@ class SiteDeviceStatsEvents(_MistWebsocket):
             time.sleep(60)
     """
 
-    def __init__(self, mist_session: APISession, site_id: str) -> None:
-        super().__init__(mist_session, channel=f"/sites/{site_id}/stats/devices")
+    def __init__(self, mist_session: APISession, site_id: str, **kwargs) -> None:
+        super().__init__(mist_session, channel=f"/sites/{site_id}/stats/devices", **kwargs)
 
 
 class SiteDeviceUpgradesEvents(_MistWebsocket):
@@ -185,8 +185,8 @@ class SiteDeviceUpgradesEvents(_MistWebsocket):
             time.sleep(60)
     """
 
-    def __init__(self, mist_session: APISession, site_id: str) -> None:
-        super().__init__(mist_session, channel=f"/sites/{site_id}/devices")
+    def __init__(self, mist_session: APISession, site_id: str, **kwargs) -> None:
+        super().__init__(mist_session, channel=f"/sites/{site_id}/devices", **kwargs)
 
 
 class SiteMxEdgesStatsEvents(_MistWebsocket):
@@ -226,8 +226,8 @@ class SiteMxEdgesStatsEvents(_MistWebsocket):
             time.sleep(60)
     """
 
-    def __init__(self, mist_session: APISession, site_id: str) -> None:
-        super().__init__(mist_session, channel=f"/sites/{site_id}/stats/mxedges")
+    def __init__(self, mist_session: APISession, site_id: str, **kwargs) -> None:
+        super().__init__(mist_session, channel=f"/sites/{site_id}/stats/mxedges", **kwargs)
 
 
 class SitePcapEvents(_MistWebsocket):
@@ -267,5 +267,5 @@ class SitePcapEvents(_MistWebsocket):
             time.sleep(60)
     """
 
-    def __init__(self, mist_session: APISession, site_id: str) -> None:
-        super().__init__(mist_session, channel=f"/sites/{site_id}/pcap")
+    def __init__(self, mist_session: APISession, site_id: str, **kwargs) -> None:
+        super().__init__(mist_session, channel=f"/sites/{site_id}/pcap", **kwargs)