kstlib 0.0.1a0__py3-none-any.whl → 1.0.0__py3-none-any.whl

kstlib/websocket/__init__.py

@@ -0,0 +1,97 @@
+"""WebSocket client with proactive connection control.
+
+This module provides WebSocketManager, an async WebSocket client that offers
+proactive control over connections rather than just reactive reconnection.
+
+The key differentiator is the ability to control WHEN to disconnect/reconnect
+rather than just reacting to disconnections. This is essential for trading
+applications where you want to avoid disconnections during critical operations.
+
+Features:
+    - **Proactive Control**: User-controlled disconnect/reconnect timing
+    - **Auto-Reconnection**: Configurable reconnection strategies
+    - **Subscription Management**: Auto-resubscribe on reconnection
+    - **Statistics Tracking**: Proactive vs reactive disconnect metrics
+    - **Config-Driven**: Integrates with kstlib.conf.yml
+
+Examples:
+    Basic usage:
+
+    >>> from kstlib.websocket import WebSocketManager
+    >>> async def main():  # doctest: +SKIP
+    ...     async with WebSocketManager("wss://example.com/ws") as ws:
+    ...         async for message in ws.stream():
+    ...             print(message)
+
+    Proactive control for trading:
+
+    >>> def next_candle_in() -> float:  # doctest: +SKIP
+    ...     '''Seconds until next 4H candle.'''
+    ...     ...
+    >>> async def trading():  # doctest: +SKIP
+    ...     ws = WebSocketManager(
+    ...         url="wss://stream.binance.com/ws/btcusdt@kline_4h",
+    ...         # Disconnect when > 30s until next candle
+    ...         should_disconnect=lambda: next_candle_in() > 30,
+    ...         # Reconnect when < 60s until next candle
+    ...         should_reconnect=lambda: next_candle_in() < 60,
+    ...         disconnect_check_interval=5.0,
+    ...     )
+    ...     async with ws:
+    ...         async for candle in ws.stream():
+    ...             if candle.get("k", {}).get("x"):
+    ...                 process_candle(candle)
+
+Note:
+    Requires the ``websockets`` package. Install with::
+
+        pip install kstlib[websocket]
+"""
+
+from kstlib.websocket.exceptions import (
+    WebSocketClosedError,
+    WebSocketConnectionError,
+    WebSocketError,
+    WebSocketProtocolError,
+    WebSocketQueueFullError,
+    WebSocketReconnectError,
+    WebSocketTimeoutError,
+)
+from kstlib.websocket.models import (
+    ConnectionState,
+    DisconnectReason,
+    ReconnectStrategy,
+    WebSocketStats,
+)
+
+# Lazy import for WebSocketManager to avoid ImportError if websockets not installed
+_websocket_manager = None
+
+
+def __getattr__(name: str) -> type:
+    """Lazy load WebSocketManager to avoid ImportError if websockets not installed."""
+    if name == "WebSocketManager":
+        global _websocket_manager
+        if _websocket_manager is None:
+            from kstlib.websocket.manager import WebSocketManager
+
+            _websocket_manager = WebSocketManager
+        return _websocket_manager
+    msg = f"module {__name__!r} has no attribute {name!r}"
+    raise AttributeError(msg)
+
+
+__all__ = [
+    "ConnectionState",
+    "DisconnectReason",
+    "ReconnectStrategy",
+    "WebSocketClosedError",
+    "WebSocketConnectionError",
+    "WebSocketError",
+    "WebSocketManager",
+    "WebSocketProtocolError",
+    "WebSocketQueueFullError",
+    "WebSocketReconnectError",
+    "WebSocketStats",
+    "WebSocketTimeoutError",
+]

kstlib/websocket/exceptions.py

@@ -0,0 +1,214 @@
+"""WebSocket exception hierarchy.
+
+All WebSocket exceptions inherit from WebSocketError, allowing users to catch
+all WebSocket-specific errors with a single except clause.
+
+Example:
+    >>> from kstlib.websocket import WebSocketError
+    >>> try:
+    ...     await manager.connect()
+    ... except WebSocketError as e:  # doctest: +SKIP
+    ...     print(f"WebSocket error: {e}")
+"""
+
+from __future__ import annotations
+
+from kstlib.config.exceptions import KstlibError
+
+__all__ = [
+    "WebSocketClosedError",
+    "WebSocketConnectionError",
+    "WebSocketError",
+    "WebSocketProtocolError",
+    "WebSocketQueueFullError",
+    "WebSocketReconnectError",
+    "WebSocketTimeoutError",
+]
+
+
+class WebSocketError(KstlibError):
+    """Base exception for all WebSocket errors.
+
+    All WebSocket-specific exceptions inherit from this class,
+    allowing for easy catching of any WebSocket error.
+    """
+
+
+class WebSocketConnectionError(WebSocketError, ConnectionError):
+    """Failed to establish WebSocket connection.
+
+    Raised when the initial connection or reconnection fails after
+    exhausting all retry attempts.
+
+    Attributes:
+        url: The WebSocket URL that failed to connect.
+        attempts: Number of connection attempts made.
+        last_error: The underlying error from the last attempt.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        url: str = "",
+        attempts: int = 0,
+        last_error: BaseException | None = None,
+    ) -> None:
+        """Initialize connection error.
+
+        Args:
+            message: Human-readable error description.
+            url: The WebSocket URL that failed to connect.
+            attempts: Number of connection attempts made.
+            last_error: The underlying error from the last attempt.
+        """
+        super().__init__(message)
+        self.url = url
+        self.attempts = attempts
+        self.last_error = last_error
+
+
+class WebSocketClosedError(WebSocketError):
+    """WebSocket connection was closed.
+
+    Raised when the connection is closed unexpectedly by the server
+    or due to a protocol error.
+
+    Attributes:
+        code: WebSocket close code (1000-4999).
+        reason: Optional human-readable close reason.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: int = 1006,
+        reason: str = "",
+    ) -> None:
+        """Initialize closed error.
+
+        Args:
+            message: Human-readable error description.
+            code: WebSocket close code (1000-4999).
+            reason: Optional human-readable close reason.
+        """
+        super().__init__(message)
+        self.code = code
+        self.reason = reason
+
+
+class WebSocketTimeoutError(WebSocketError, TimeoutError):
+    """WebSocket operation timed out.
+
+    Raised when a WebSocket operation (connect, ping, receive) exceeds
+    its configured timeout.
+
+    Attributes:
+        operation: The operation that timed out (connect, ping, receive).
+        timeout: The timeout value in seconds.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        operation: str = "",
+        timeout: float = 0.0,
+    ) -> None:
+        """Initialize timeout error.
+
+        Args:
+            message: Human-readable error description.
+            operation: The operation that timed out.
+            timeout: The timeout value in seconds.
+        """
+        super().__init__(message)
+        self.operation = operation
+        self.timeout = timeout
+
+
+class WebSocketReconnectError(WebSocketError):
+    """Failed to reconnect after disconnection.
+
+    Raised when all reconnection attempts have been exhausted
+    without successfully re-establishing the connection.
+
+    Attributes:
+        attempts: Total number of reconnection attempts made.
+        last_error: The underlying error from the last attempt.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        attempts: int = 0,
+        last_error: BaseException | None = None,
+    ) -> None:
+        """Initialize reconnect error.
+
+        Args:
+            message: Human-readable error description.
+            attempts: Total number of reconnection attempts made.
+            last_error: The underlying error from the last attempt.
+        """
+        super().__init__(message)
+        self.attempts = attempts
+        self.last_error = last_error
+
+
+class WebSocketProtocolError(WebSocketError):
+    """WebSocket protocol violation.
+
+    Raised when the server or client violates the WebSocket protocol,
+    such as sending malformed frames or invalid data.
+
+    Attributes:
+        protocol_error: Description of the protocol violation.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        protocol_error: str = "",
+    ) -> None:
+        """Initialize protocol error.
+
+        Args:
+            message: Human-readable error description.
+            protocol_error: Description of the protocol violation.
+        """
+        super().__init__(message)
+        self.protocol_error = protocol_error
+
+
+class WebSocketQueueFullError(WebSocketError):
+    """Message queue is full.
+
+    Raised when the incoming message queue is full and cannot accept
+    more messages. This typically indicates the consumer is too slow.
+
+    Attributes:
+        queue_size: Maximum queue size that was exceeded.
+        dropped_count: Number of messages dropped due to queue overflow.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        queue_size: int = 0,
+        dropped_count: int = 0,
+    ) -> None:
+        """Initialize queue full error.
+
+        Args:
+            message: Human-readable error description.
+            queue_size: Maximum queue size that was exceeded.
+            dropped_count: Number of messages dropped due to queue overflow.
+        """
+        super().__init__(message)
+        self.queue_size = queue_size
+        self.dropped_count = dropped_count