WebSocket Exceptions¶

Exception hierarchy for the websocket subsystem.

Exception Hierarchy¶

KstlibError
└── WebSocketError
    ├── WebSocketConnectionError
    ├── WebSocketClosedError
    ├── WebSocketTimeoutError
    ├── WebSocketReconnectError
    ├── WebSocketProtocolError
    └── WebSocketQueueFullError

Base Exception¶

exception kstlib.websocket.exceptions.WebSocketError[source]¶

Bases: KstlibError

Base exception for all WebSocket errors.

All WebSocket-specific exceptions inherit from this class, allowing for easy catching of any WebSocket error.

Connection Errors¶

exception kstlib.websocket.exceptions.WebSocketConnectionError(message, *, url='', attempts=0, last_error=None)[source]¶

Bases: WebSocketError, ConnectionError

Failed to establish WebSocket connection.

Raised when the initial connection or reconnection fails after exhausting all retry attempts.

url¶: The WebSocket URL that failed to connect.

attempts¶: Number of connection attempts made.

last_error¶: The underlying error from the last attempt.

__init__(self, message: 'str', *, url: 'str' = '', attempts: 'int' = 0, last_error: 'BaseException | None' = None) → 'None' -> None[source]¶

Initialize connection error.

Parameters:

message (str) – Human-readable error description.
url (str) – The WebSocket URL that failed to connect.
attempts (int) – Number of connection attempts made.
last_error (BaseException | None) – The underlying error from the last attempt.

Raised when connection fails:

Initial connection failure
All retry attempts exhausted
DNS resolution failure

Attributes:

url: The WebSocket URL that failed
attempts: Number of connection attempts made
last_error: The underlying error from the last attempt

Closed Errors¶

exception kstlib.websocket.exceptions.WebSocketClosedError(message, *, code=1006, reason='')[source]¶

Bases: WebSocketError

WebSocket connection was closed.

Raised when the connection is closed unexpectedly by the server or due to a protocol error.

code¶: WebSocket close code (1000-4999).

reason¶: Optional human-readable close reason.

__init__(self, message: 'str', *, code: 'int' = 1006, reason: 'str' = '') → 'None' -> None[source]¶

Initialize closed error.

Parameters:

message (str) – Human-readable error description.
code (int) – WebSocket close code (1000-4999).
reason (str) – Optional human-readable close reason.

Raised when connection is closed unexpectedly:

Server initiated close
Protocol error close
Network disconnection

Attributes:

code: WebSocket close code (1000-4999)
reason: Human-readable close reason

Timeout Errors¶

exception kstlib.websocket.exceptions.WebSocketTimeoutError(message, *, operation='', timeout=0.0)[source]¶

Bases: WebSocketError, TimeoutError

WebSocket operation timed out.

Raised when a WebSocket operation (connect, ping, receive) exceeds its configured timeout.

operation¶: The operation that timed out (connect, ping, receive).

timeout¶: The timeout value in seconds.

__init__(self, message: 'str', *, operation: 'str' = '', timeout: 'float' = 0.0) → 'None' -> None[source]¶

Initialize timeout error.

Parameters:

message (str) – Human-readable error description.
operation (str) – The operation that timed out.
timeout (float) – The timeout value in seconds.

Raised when operations time out:

Connection timeout
Ping/pong timeout
Receive timeout

Attributes:

operation: The operation that timed out
timeout: The timeout value in seconds

Reconnect Errors¶

exception kstlib.websocket.exceptions.WebSocketReconnectError(message, *, attempts=0, last_error=None)[source]¶

Bases: WebSocketError

Failed to reconnect after disconnection.

Raised when all reconnection attempts have been exhausted without successfully re-establishing the connection.

attempts¶: Total number of reconnection attempts made.

last_error¶: The underlying error from the last attempt.

__init__(self, message: 'str', *, attempts: 'int' = 0, last_error: 'BaseException | None' = None) → 'None' -> None[source]¶

Initialize reconnect error.

Parameters:

message (str) – Human-readable error description.
attempts (int) – Total number of reconnection attempts made.
last_error (BaseException | None) – The underlying error from the last attempt.

Raised when reconnection fails:

All reconnection attempts exhausted
Reconnection disabled

Attributes:

attempts: Total reconnection attempts made
last_error: The underlying error from the last attempt

Protocol Errors¶

exception kstlib.websocket.exceptions.WebSocketProtocolError(message, *, protocol_error='')[source]¶

Bases: WebSocketError

WebSocket protocol violation.

Raised when the server or client violates the WebSocket protocol, such as sending malformed frames or invalid data.

protocol_error¶: Description of the protocol violation.

__init__(self, message: 'str', *, protocol_error: 'str' = '') → 'None' -> None[source]¶

Initialize protocol error.

Parameters:

message (str) – Human-readable error description.
protocol_error (str) – Description of the protocol violation.

Raised on protocol violations:

Malformed frames
Invalid data format
Protocol state violations

Attributes:

protocol_error: Description of the protocol violation

Queue Errors¶

exception kstlib.websocket.exceptions.WebSocketQueueFullError(message, *, queue_size=0, dropped_count=0)[source]¶

Bases: 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.

queue_size¶: Maximum queue size that was exceeded.

dropped_count¶: Number of messages dropped due to queue overflow.

__init__(self, message: 'str', *, queue_size: 'int' = 0, dropped_count: 'int' = 0) → 'None' -> None[source]¶

Initialize queue full error.

Parameters:

message (str) – Human-readable error description.
queue_size (int) – Maximum queue size that was exceeded.
dropped_count (int) – Number of messages dropped due to queue overflow.

Raised when message queue is full:

Consumer too slow
Burst of messages

Attributes:

queue_size: Maximum queue size exceeded
dropped_count: Number of messages dropped

Usage Examples¶

from kstlib.websocket import (
    WebSocketError,
    WebSocketConnectionError,
    WebSocketClosedError,
    WebSocketTimeoutError,
    WebSocketReconnectError,
)

try:
    async with WebSocketManager(url) as ws:
        async for message in ws.stream():
            process(message)
except WebSocketConnectionError as e:
    log.error(f"Failed to connect to {e.url} after {e.attempts} attempts")
except WebSocketClosedError as e:
    log.warning(f"Connection closed: {e.code} - {e.reason}")
except WebSocketTimeoutError as e:
    log.warning(f"Timeout during {e.operation}: {e.timeout}s")
except WebSocketReconnectError as e:
    log.error(f"Reconnection failed after {e.attempts} attempts")
except WebSocketError as e:
    log.error(f"WebSocket error: {e}")