docs(websockets): clarify ping_timeout derivation and queue_maxsize scope

- note that ping_timeout falls back to 45 when ping_interval=0 (pings
  disabled, value unused) in the constants comment, README, and all
  channel class docstrings
- document that queue_maxsize bounds both the receive() and callback
  queues in the channel class docstrings

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: tmunzer-AIDE

README.md

@@ -584,7 +584,7 @@ All channel classes accept the following optional keyword arguments:
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `ping_interval` | `int` | `60` | Seconds between automatic ping frames. Set to `0` to disable pings. |
-| `ping_timeout` | `int \| None` | `None` | Seconds to wait for a pong response before treating the connection as dead. Defaults to `min(45, ping_interval - 1)`. When `ping_interval > 0`, this must be lower than `ping_interval`. |
+| `ping_timeout` | `int \| None` | `None` | Seconds to wait for a pong response before treating the connection as dead. Defaults to `min(45, ping_interval - 1)` when pings are enabled, or `45` when `ping_interval=0` (unused since pings are disabled). When `ping_interval > 0`, this must be lower than `ping_interval`. |
 | `auto_reconnect` | `bool` | `False` | Automatically reconnect on transient failures using exponential backoff. |
 | `max_reconnect_attempts` | `int` | `5` | Maximum number of reconnect attempts before giving up. |
 | `reconnect_backoff` | `float` | `2.0` | Base backoff delay in seconds. Doubles after each failed attempt (2s, 4s, 8s, ...). Resets on successful reconnection. |

src/mistapi/websockets/__ws_client.py

@@ -53,8 +53,9 @@ def filter(self, record: logging.LogRecord) -> bool:
 MAX_CHANNELS_PER_CONNECTION = 2000
 HIGH_CHANNEL_COUNT_WARNING = 1500
 
-# Default pong timeout, and the value ping_timeout is derived from when only
-# ping_interval is supplied (min(DEFAULT_PING_TIMEOUT, ping_interval - 1)).
+# Default pong timeout. When ping_timeout is not supplied it is derived as
+# min(DEFAULT_PING_TIMEOUT, ping_interval - 1), or DEFAULT_PING_TIMEOUT when
+# ping_interval is 0 (pings disabled, so the value is unused).
 DEFAULT_PING_TIMEOUT = 45
 
 

src/mistapi/websockets/location.py

@@ -33,8 +33,10 @@ class BleAssetsEvents(_MistWebsocket):
         Interval in seconds to send WebSocket ping frames (keep-alive).
     ping_timeout : int | None, default None
         Time in seconds to wait for a ping response before considering the
-        connection dead. Defaults to ``min(45, ping_interval - 1)``. Must be
-        lower than ping_interval.
+        connection dead. Defaults to ``min(45, ping_interval - 1)`` when
+        pings are enabled, or ``45`` when ``ping_interval`` is 0 (unused
+        since pings are disabled). Must be lower than ping_interval when
+        pings are enabled.
     auto_reconnect : bool, default False
         Automatically reconnect on unexpected disconnections using exponential backoff.
     max_reconnect_attempts : int, default 5
@@ -44,10 +46,11 @@ class BleAssetsEvents(_MistWebsocket):
     max_reconnect_backoff : float | None, default None
         Maximum backoff delay in seconds. If None, backoff grows indefinitely.
     queue_maxsize : int, default 0
-        Maximum number of messages buffered in the internal queue for the
-        ``receive()`` generator. ``0`` means unbounded. When set,
-        incoming messages are dropped with a warning when the queue is
-        full, preventing memory growth on high-frequency streams.
+        Maximum number of messages buffered in each of the internal queues
+        used for the ``receive()`` generator and callback delivery. ``0``
+        means unbounded. When set, incoming messages are dropped with a
+        warning when the target queue is full, preventing memory growth on
+        high-frequency streams.
     subscription_watchdog_timeout : float, default 10.0
         Maximum time in seconds to wait for all channel subscription
         acknowledgements after connect. On timeout, the error is reported to
@@ -136,8 +139,10 @@ class ConnectedClientsEvents(_MistWebsocket):
         Interval in seconds to send WebSocket ping frames (keep-alive).
     ping_timeout : int | None, default None
         Time in seconds to wait for a ping response before considering the
-        connection dead. Defaults to ``min(45, ping_interval - 1)``. Must be
-        lower than ping_interval.
+        connection dead. Defaults to ``min(45, ping_interval - 1)`` when
+        pings are enabled, or ``45`` when ``ping_interval`` is 0 (unused
+        since pings are disabled). Must be lower than ping_interval when
+        pings are enabled.
     auto_reconnect : bool, default False
         Automatically reconnect on unexpected disconnections using exponential backoff.
     max_reconnect_attempts : int, default 5
@@ -147,10 +152,11 @@ class ConnectedClientsEvents(_MistWebsocket):
     max_reconnect_backoff : float | None, default None
         Maximum backoff delay in seconds. If None, backoff grows indefinitely.
     queue_maxsize : int, default 0
-        Maximum number of messages buffered in the internal queue for the
-        ``receive()`` generator. ``0`` means unbounded. When set,
-        incoming messages are dropped with a warning when the queue is
-        full, preventing memory growth on high-frequency streams.
+        Maximum number of messages buffered in each of the internal queues
+        used for the ``receive()`` generator and callback delivery. ``0``
+        means unbounded. When set, incoming messages are dropped with a
+        warning when the target queue is full, preventing memory growth on
+        high-frequency streams.
     subscription_watchdog_timeout : float, default 10.0
         Maximum time in seconds to wait for all channel subscription
         acknowledgements after connect. On timeout, the error is reported to
@@ -239,8 +245,10 @@ class SdkClientsEvents(_MistWebsocket):
         Interval in seconds to send WebSocket ping frames (keep-alive).
     ping_timeout : int | None, default None
         Time in seconds to wait for a ping response before considering the
-        connection dead. Defaults to ``min(45, ping_interval - 1)``. Must be
-        lower than ping_interval.
+        connection dead. Defaults to ``min(45, ping_interval - 1)`` when
+        pings are enabled, or ``45`` when ``ping_interval`` is 0 (unused
+        since pings are disabled). Must be lower than ping_interval when
+        pings are enabled.
     auto_reconnect : bool, default False
         Automatically reconnect on unexpected disconnections using exponential backoff.
     max_reconnect_attempts : int, default 5
@@ -250,10 +258,11 @@ class SdkClientsEvents(_MistWebsocket):
     max_reconnect_backoff : float | None, default None
         Maximum backoff delay in seconds. If None, backoff grows indefinitely.
     queue_maxsize : int, default 0
-        Maximum number of messages buffered in the internal queue for the
-        ``receive()`` generator. ``0`` means unbounded. When set,
-        incoming messages are dropped with a warning when the queue is
-        full, preventing memory growth on high-frequency streams.
+        Maximum number of messages buffered in each of the internal queues
+        used for the ``receive()`` generator and callback delivery. ``0``
+        means unbounded. When set, incoming messages are dropped with a
+        warning when the target queue is full, preventing memory growth on
+        high-frequency streams.
     subscription_watchdog_timeout : float, default 10.0
         Maximum time in seconds to wait for all channel subscription
         acknowledgements after connect. On timeout, the error is reported to
@@ -342,8 +351,10 @@ class UnconnectedClientsEvents(_MistWebsocket):
         Interval in seconds to send WebSocket ping frames (keep-alive).
     ping_timeout : int | None, default None
         Time in seconds to wait for a ping response before considering the
-        connection dead. Defaults to ``min(45, ping_interval - 1)``. Must be
-        lower than ping_interval.
+        connection dead. Defaults to ``min(45, ping_interval - 1)`` when
+        pings are enabled, or ``45`` when ``ping_interval`` is 0 (unused
+        since pings are disabled). Must be lower than ping_interval when
+        pings are enabled.
     auto_reconnect : bool, default False
         Automatically reconnect on unexpected disconnections using exponential backoff.
     max_reconnect_attempts : int, default 5
@@ -353,10 +364,11 @@ class UnconnectedClientsEvents(_MistWebsocket):
     max_reconnect_backoff : float | None, default None
         Maximum backoff delay in seconds. If None, backoff grows indefinitely.
     queue_maxsize : int, default 0
-        Maximum number of messages buffered in the internal queue for the
-        ``receive()`` generator. ``0`` means unbounded. When set,
-        incoming messages are dropped with a warning when the queue is
-        full, preventing memory growth on high-frequency streams.
+        Maximum number of messages buffered in each of the internal queues
+        used for the ``receive()`` generator and callback delivery. ``0``
+        means unbounded. When set, incoming messages are dropped with a
+        warning when the target queue is full, preventing memory growth on
+        high-frequency streams.
     subscription_watchdog_timeout : float, default 10.0
         Maximum time in seconds to wait for all channel subscription
         acknowledgements after connect. On timeout, the error is reported to
@@ -447,8 +459,10 @@ class DiscoveredBleAssetsEvents(_MistWebsocket):
         Interval in seconds to send WebSocket ping frames (keep-alive).
     ping_timeout : int | None, default None
         Time in seconds to wait for a ping response before considering the
-        connection dead. Defaults to ``min(45, ping_interval - 1)``. Must be
-        lower than ping_interval.
+        connection dead. Defaults to ``min(45, ping_interval - 1)`` when
+        pings are enabled, or ``45`` when ``ping_interval`` is 0 (unused
+        since pings are disabled). Must be lower than ping_interval when
+        pings are enabled.
     auto_reconnect : bool, default False
         Automatically reconnect on unexpected disconnections using exponential backoff.
     max_reconnect_attempts : int, default 5
@@ -458,10 +472,11 @@ class DiscoveredBleAssetsEvents(_MistWebsocket):
     max_reconnect_backoff : float | None, default None
         Maximum backoff delay in seconds. If None, backoff grows indefinitely.
     queue_maxsize : int, default 0
-        Maximum number of messages buffered in the internal queue for the
-        ``receive()`` generator. ``0`` means unbounded. When set,
-        incoming messages are dropped with a warning when the queue is
-        full, preventing memory growth on high-frequency streams.
+        Maximum number of messages buffered in each of the internal queues
+        used for the ``receive()`` generator and callback delivery. ``0``
+        means unbounded. When set, incoming messages are dropped with a
+        warning when the target queue is full, preventing memory growth on
+        high-frequency streams.
     subscription_watchdog_timeout : float, default 10.0
         Maximum time in seconds to wait for all channel subscription
         acknowledgements after connect. On timeout, the error is reported to

src/mistapi/websockets/orgs.py

@@ -31,8 +31,10 @@ class InsightsEvents(_MistWebsocket):
         Interval in seconds to send WebSocket ping frames (keep-alive).
     ping_timeout : int | None, default None
         Time in seconds to wait for a ping response before considering the
-        connection dead. Defaults to ``min(45, ping_interval - 1)``. Must be
-        lower than ping_interval.
+        connection dead. Defaults to ``min(45, ping_interval - 1)`` when
+        pings are enabled, or ``45`` when ``ping_interval`` is 0 (unused
+        since pings are disabled). Must be lower than ping_interval when
+        pings are enabled.
     auto_reconnect : bool, default False
         Automatically reconnect on unexpected disconnections using exponential backoff.
     max_reconnect_attempts : int, default 5
@@ -42,10 +44,11 @@ class InsightsEvents(_MistWebsocket):
     max_reconnect_backoff : float | None, default None
         Maximum backoff delay in seconds. If None, backoff grows indefinitely.
     queue_maxsize : int, default 0
-        Maximum number of messages buffered in the internal queue for the
-        ``receive()`` generator. ``0`` means unbounded. When set,
-        incoming messages are dropped with a warning when the queue is
-        full, preventing memory growth on high-frequency streams.
+        Maximum number of messages buffered in each of the internal queues
+        used for the ``receive()`` generator and callback delivery. ``0``
+        means unbounded. When set, incoming messages are dropped with a
+        warning when the target queue is full, preventing memory growth on
+        high-frequency streams.
     subscription_watchdog_timeout : float, default 10.0
         Maximum time in seconds to wait for all channel subscription
         acknowledgements after connect. On timeout, the error is reported to
@@ -130,8 +133,10 @@ class MxEdgesStatsEvents(_MistWebsocket):
         Interval in seconds to send WebSocket ping frames (keep-alive).
     ping_timeout : int | None, default None
         Time in seconds to wait for a ping response before considering the
-        connection dead. Defaults to ``min(45, ping_interval - 1)``. Must be
-        lower than ping_interval.
+        connection dead. Defaults to ``min(45, ping_interval - 1)`` when
+        pings are enabled, or ``45`` when ``ping_interval`` is 0 (unused
+        since pings are disabled). Must be lower than ping_interval when
+        pings are enabled.
     auto_reconnect : bool, default False
         Automatically reconnect on unexpected disconnections using exponential backoff.
     max_reconnect_attempts : int, default 5
@@ -141,10 +146,11 @@ class MxEdgesStatsEvents(_MistWebsocket):
     max_reconnect_backoff : float | None, default None
         Maximum backoff delay in seconds. If None, backoff grows indefinitely.
     queue_maxsize : int, default 0
-        Maximum number of messages buffered in the internal queue for the
-        ``receive()`` generator. ``0`` means unbounded. When set,
-        incoming messages are dropped with a warning when the queue is
-        full, preventing memory growth on high-frequency streams.
+        Maximum number of messages buffered in each of the internal queues
+        used for the ``receive()`` generator and callback delivery. ``0``
+        means unbounded. When set, incoming messages are dropped with a
+        warning when the target queue is full, preventing memory growth on
+        high-frequency streams.
     subscription_watchdog_timeout : float, default 10.0
         Maximum time in seconds to wait for all channel subscription
         acknowledgements after connect. On timeout, the error is reported to
@@ -229,8 +235,10 @@ class MxEdgesEvents(_MistWebsocket):
         Interval in seconds to send WebSocket ping frames (keep-alive).
     ping_timeout : int | None, default None
         Time in seconds to wait for a ping response before considering the
-        connection dead. Defaults to ``min(45, ping_interval - 1)``. Must be
-        lower than ping_interval.
+        connection dead. Defaults to ``min(45, ping_interval - 1)`` when
+        pings are enabled, or ``45`` when ``ping_interval`` is 0 (unused
+        since pings are disabled). Must be lower than ping_interval when
+        pings are enabled.
     auto_reconnect : bool, default False
         Automatically reconnect on unexpected disconnections using exponential backoff.
     max_reconnect_attempts : int, default 5
@@ -240,10 +248,11 @@ class MxEdgesEvents(_MistWebsocket):
     max_reconnect_backoff : float | None, default None
         Maximum backoff delay in seconds. If None, backoff grows indefinitely.
     queue_maxsize : int, default 0
-        Maximum number of messages buffered in the internal queue for the
-        ``receive()`` generator. ``0`` means unbounded. When set,
-        incoming messages are dropped with a warning when the queue is
-        full, preventing memory growth on high-frequency streams.
+        Maximum number of messages buffered in each of the internal queues
+        used for the ``receive()`` generator and callback delivery. ``0``
+        means unbounded. When set, incoming messages are dropped with a
+        warning when the target queue is full, preventing memory growth on
+        high-frequency streams.
     subscription_watchdog_timeout : float, default 10.0
         Maximum time in seconds to wait for all channel subscription
         acknowledgements after connect. On timeout, the error is reported to

src/mistapi/websockets/session.py

@@ -40,8 +40,10 @@ class SessionWithUrl(_MistWebsocket):
         Interval in seconds to send WebSocket ping frames (keep-alive).
     ping_timeout : int | None, default None
         Time in seconds to wait for a ping response before considering the
-        connection dead. Defaults to ``min(45, ping_interval - 1)``. Must be
-        lower than ping_interval.
+        connection dead. Defaults to ``min(45, ping_interval - 1)`` when
+        pings are enabled, or ``45`` when ``ping_interval`` is 0 (unused
+        since pings are disabled). Must be lower than ping_interval when
+        pings are enabled.
     auto_reconnect : bool, default False
         Automatically reconnect on unexpected disconnections using exponential backoff.
     max_reconnect_attempts : int, default 5
@@ -51,10 +53,11 @@ class SessionWithUrl(_MistWebsocket):
     max_reconnect_backoff : float | None, default None
         Maximum backoff delay in seconds. If None, backoff grows indefinitely.
     queue_maxsize : int, default 0
-        Maximum number of messages buffered in the internal queue for the
-        ``receive()`` generator. ``0`` means unbounded. When set,
-        incoming messages are dropped with a warning when the queue is
-        full, preventing memory growth on high-frequency streams.
+        Maximum number of messages buffered in each of the internal queues
+        used for the ``receive()`` generator and callback delivery. ``0``
+        means unbounded. When set, incoming messages are dropped with a
+        warning when the target queue is full, preventing memory growth on
+        high-frequency streams.
     subscription_watchdog_timeout : float, default 10.0
         Maximum time in seconds to wait for all channel subscription
         acknowledgements after connect. On timeout, the error is reported to