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

kstlib/websocket/models.py

@@ -0,0 +1,361 @@
+"""WebSocket data models and enumerations.
+
+This module provides the core data structures for the WebSocket manager:
+
+- **ConnectionState**: State machine for connection lifecycle
+- **DisconnectReason**: Categorizes disconnection causes (proactive vs reactive)
+- **ReconnectStrategy**: Available reconnection strategies
+- **WebSocketStats**: Connection and message statistics
+
+Examples:
+    >>> from kstlib.websocket.models import ConnectionState, DisconnectReason
+    >>> state = ConnectionState.CONNECTED
+    >>> reason = DisconnectReason.USER_REQUESTED
+    >>> reason.is_proactive
+    True
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from enum import Enum, auto
+
+__all__ = [
+    "ConnectionState",
+    "DisconnectReason",
+    "ReconnectStrategy",
+    "WebSocketStats",
+]
+
+
+class ConnectionState(Enum):
+    """WebSocket connection state machine.
+
+    State transitions:
+        DISCONNECTED -> CONNECTING -> CONNECTED
+        CONNECTED -> RECONNECTING -> CONNECTED (on success)
+        CONNECTED -> RECONNECTING -> DISCONNECTED (on failure)
+        CONNECTED -> CLOSING -> CLOSED
+        Any state -> CLOSED (on force_close)
+
+    Attributes:
+        DISCONNECTED: Initial state, not connected.
+        CONNECTING: Connection attempt in progress.
+        CONNECTED: WebSocket connection is active.
+        RECONNECTING: Attempting to restore lost connection.
+        CLOSING: Graceful shutdown in progress.
+        CLOSED: Terminal state, cannot reconnect.
+    """
+
+    DISCONNECTED = auto()
+    CONNECTING = auto()
+    CONNECTED = auto()
+    RECONNECTING = auto()
+    CLOSING = auto()
+    CLOSED = auto()
+
+    def can_connect(self) -> bool:
+        """Check if a connection attempt is allowed from this state.
+
+        Returns:
+            True if connect() can be called from this state.
+
+        Examples:
+            >>> ConnectionState.DISCONNECTED.can_connect()
+            True
+            >>> ConnectionState.CONNECTED.can_connect()
+            False
+        """
+        return self in (ConnectionState.DISCONNECTED, ConnectionState.RECONNECTING)
+
+    def can_send(self) -> bool:
+        """Check if sending messages is allowed from this state.
+
+        Returns:
+            True if send() can be called from this state.
+
+        Examples:
+            >>> ConnectionState.CONNECTED.can_send()
+            True
+            >>> ConnectionState.DISCONNECTED.can_send()
+            False
+        """
+        return self == ConnectionState.CONNECTED
+
+    def is_terminal(self) -> bool:
+        """Check if this is a terminal state.
+
+        Returns:
+            True if no further state transitions are possible.
+
+        Examples:
+            >>> ConnectionState.CLOSED.is_terminal()
+            True
+            >>> ConnectionState.DISCONNECTED.is_terminal()
+            False
+        """
+        return self == ConnectionState.CLOSED
+
+
+class DisconnectReason(Enum):
+    """Reason for WebSocket disconnection.
+
+    Disconnections are categorized as either proactive (user-controlled)
+    or reactive (forced by external factors). This distinction is key
+    for the proactive connection control feature.
+
+    Proactive reasons (user-controlled):
+        USER_REQUESTED: Manual disconnect via request_disconnect()
+        SCHEDULED: Disconnect triggered by schedule_reconnect()
+        CALLBACK_TRIGGERED: should_disconnect() callback returned True
+        CONNECTION_LIMIT: Preemptive disconnect before platform limit
+
+    Reactive reasons (forced):
+        SERVER_CLOSED: Server initiated the close
+        NETWORK_ERROR: Network connectivity issue
+        PING_TIMEOUT: No pong response within timeout
+        PROTOCOL_ERROR: WebSocket protocol violation
+    """
+
+    # Proactive (user-controlled) disconnections
+    USER_REQUESTED = auto()
+    SCHEDULED = auto()
+    CALLBACK_TRIGGERED = auto()
+    CONNECTION_LIMIT = auto()
+
+    # Reactive (forced) disconnections
+    SERVER_CLOSED = auto()
+    NETWORK_ERROR = auto()
+    PING_TIMEOUT = auto()
+    PROTOCOL_ERROR = auto()
+    KILLED = auto()  # Simulated external kill (e.g., Binance forced disconnect)
+
+    @property
+    def is_proactive(self) -> bool:
+        """Check if this is a proactive (user-controlled) disconnection.
+
+        Returns:
+            True if the disconnection was initiated by the user/application.
+
+        Examples:
+            >>> DisconnectReason.USER_REQUESTED.is_proactive
+            True
+            >>> DisconnectReason.NETWORK_ERROR.is_proactive
+            False
+        """
+        return self in (
+            DisconnectReason.USER_REQUESTED,
+            DisconnectReason.SCHEDULED,
+            DisconnectReason.CALLBACK_TRIGGERED,
+            DisconnectReason.CONNECTION_LIMIT,
+        )
+
+    @property
+    def is_reactive(self) -> bool:
+        """Check if this is a reactive (forced) disconnection.
+
+        Returns:
+            True if the disconnection was forced by external factors.
+
+        Examples:
+            >>> DisconnectReason.SERVER_CLOSED.is_reactive
+            True
+            >>> DisconnectReason.USER_REQUESTED.is_reactive
+            False
+        """
+        return not self.is_proactive
+
+
+class ReconnectStrategy(Enum):
+    """Reconnection strategy after disconnection.
+
+    Attributes:
+        IMMEDIATE: Reconnect immediately without delay.
+        FIXED_DELAY: Wait a fixed delay before each attempt.
+        EXPONENTIAL_BACKOFF: Exponentially increasing delays.
+        CALLBACK_CONTROLLED: Reconnection timing controlled by callback.
+    """
+
+    IMMEDIATE = auto()
+    FIXED_DELAY = auto()
+    EXPONENTIAL_BACKOFF = auto()
+    CALLBACK_CONTROLLED = auto()
+
+
+@dataclass
+class WebSocketStats:
+    """WebSocket connection and message statistics.
+
+    Tracks both connection lifecycle events and message throughput.
+    The key distinction is between proactive and reactive disconnections,
+    which is central to the proactive control feature.
+
+    Attributes:
+        connects: Total successful connection count.
+        disconnects: Total disconnection count.
+        proactive_disconnects: Disconnections initiated by user/application.
+        reactive_disconnects: Disconnections forced by external factors.
+        messages_received: Total messages received.
+        messages_sent: Total messages sent.
+        bytes_received: Total bytes received.
+        bytes_sent: Total bytes sent.
+        last_connect_time: Unix timestamp of last successful connection.
+        last_disconnect_time: Unix timestamp of last disconnection.
+        last_message_time: Unix timestamp of last message (sent or received).
+
+    Examples:
+        >>> stats = WebSocketStats()
+        >>> stats.record_connect()
+        >>> stats.connects
+        1
+        >>> stats.record_disconnect(proactive=True)
+        >>> stats.proactive_disconnects
+        1
+    """
+
+    connects: int = 0
+    disconnects: int = 0
+    proactive_disconnects: int = 0
+    reactive_disconnects: int = 0
+    messages_received: int = 0
+    messages_sent: int = 0
+    bytes_received: int = 0
+    bytes_sent: int = 0
+    last_connect_time: float = 0.0
+    last_disconnect_time: float = 0.0
+    last_message_time: float = 0.0
+    _start_time: float = field(default_factory=time.monotonic)
+
+    def record_connect(self) -> None:
+        """Record a successful connection.
+
+        Examples:
+            >>> stats = WebSocketStats()
+            >>> stats.record_connect()
+            >>> stats.connects
+            1
+        """
+        self.connects += 1
+        self.last_connect_time = time.time()
+
+    def record_disconnect(self, *, proactive: bool = False) -> None:
+        """Record a disconnection.
+
+        Args:
+            proactive: True if this was a user-initiated disconnection.
+
+        Examples:
+            >>> stats = WebSocketStats()
+            >>> stats.record_disconnect(proactive=True)
+            >>> stats.proactive_disconnects
+            1
+            >>> stats.record_disconnect(proactive=False)
+            >>> stats.reactive_disconnects
+            1
+        """
+        self.disconnects += 1
+        self.last_disconnect_time = time.time()
+        if proactive:
+            self.proactive_disconnects += 1
+        else:
+            self.reactive_disconnects += 1
+
+    def record_message_received(self, size: int = 0) -> None:
+        """Record a received message.
+
+        Args:
+            size: Size of the message in bytes.
+
+        Examples:
+            >>> stats = WebSocketStats()
+            >>> stats.record_message_received(100)
+            >>> stats.messages_received
+            1
+            >>> stats.bytes_received
+            100
+        """
+        self.messages_received += 1
+        self.bytes_received += size
+        self.last_message_time = time.time()
+
+    def record_message_sent(self, size: int = 0) -> None:
+        """Record a sent message.
+
+        Args:
+            size: Size of the message in bytes.
+
+        Examples:
+            >>> stats = WebSocketStats()
+            >>> stats.record_message_sent(50)
+            >>> stats.messages_sent
+            1
+            >>> stats.bytes_sent
+            50
+        """
+        self.messages_sent += 1
+        self.bytes_sent += size
+        self.last_message_time = time.time()
+
+    @property
+    def uptime(self) -> float:
+        """Time since stats object was created, in seconds.
+
+        Returns:
+            Elapsed time in seconds.
+
+        Examples:
+            >>> import time
+            >>> stats = WebSocketStats()
+            >>> time.sleep(0.05)
+            >>> stats.uptime > 0
+            True
+        """
+        return time.monotonic() - self._start_time
+
+    @property
+    def connection_time(self) -> float:
+        """Time since last connection, in seconds.
+
+        Returns zero if never connected.
+
+        Returns:
+            Elapsed time since last connect, or 0 if never connected.
+
+        Examples:
+            >>> stats = WebSocketStats()
+            >>> stats.connection_time
+            0.0
+            >>> stats.record_connect()
+            >>> stats.connection_time > 0 or stats.connection_time == 0.0
+            True
+        """
+        if self.last_connect_time == 0.0:
+            return 0.0
+        return time.time() - self.last_connect_time
+
+    def reset(self) -> None:
+        """Reset all statistics to zero.
+
+        Examples:
+            >>> stats = WebSocketStats()
+            >>> stats.record_connect()
+            >>> stats.record_message_sent(100)
+            >>> stats.reset()
+            >>> stats.connects
+            0
+            >>> stats.messages_sent
+            0
+        """
+        self.connects = 0
+        self.disconnects = 0
+        self.proactive_disconnects = 0
+        self.reactive_disconnects = 0
+        self.messages_received = 0
+        self.messages_sent = 0
+        self.bytes_received = 0
+        self.bytes_sent = 0
+        self.last_connect_time = 0.0
+        self.last_disconnect_time = 0.0
+        self.last_message_time = 0.0
+        self._start_time = time.monotonic()

kstlib-1.0.1.dist-info/METADATA

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: kstlib
+Version: 1.0.1
+Summary: Config-driven helpers for Python projects (dynamic config, secure secrets, preset logging, and more…)
+Author-email: Michel TRUONG <michel.truong@gmail.com>
+Maintainer-email: Michel TRUONG <michel.truong@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/KaminoU/kstlib
+Project-URL: Repository, https://github.com/KaminoU/kstlib
+Project-URL: Bug Tracker, https://github.com/KaminoU/kstlib/issues
+Project-URL: Changelog, https://github.com/KaminoU/kstlib/blob/main/CHANGELOG.md
+Keywords: kstlib
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: pyyaml<7,>=6.0
+Requires-Dist: tomli<3,>=2.3
+Requires-Dist: tomli-w<2,>=1.0
+Requires-Dist: python-box<8,>=7.3
+Requires-Dist: typer<1,>=0.19
+Requires-Dist: click<9,>=8.3
+Requires-Dist: rich<15,>=14.2
+Requires-Dist: structlog<26,>=25.0
+Requires-Dist: aiosqlite<1,>=0.21
+Requires-Dist: aiosmtplib<5,>=4.0
+Requires-Dist: websockets<16,>=15.0
+Requires-Dist: jinja2<4,>=3.1
+Requires-Dist: humanize<5,>=4.11
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: authlib<2,>=1.5
+Requires-Dist: pendulum<4,>=3.0
+Provides-Extra: dev
+Requires-Dist: pytest<9,>=8.4; extra == "dev"
+Requires-Dist: pytest-cov<8,>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio<2,>=1.2; extra == "dev"
+Requires-Dist: ruff<1,>=0.14; extra == "dev"
+Requires-Dist: mypy<2,>=1.18; extra == "dev"
+Requires-Dist: types-PyYAML<7,>=6.0; extra == "dev"
+Requires-Dist: pre-commit<5,>=4.0; extra == "dev"
+Requires-Dist: boto3<2,>=1.35; extra == "dev"
+Provides-Extra: db-crypto
+Requires-Dist: sqlcipher3<1,>=0.5; extra == "db-crypto"
+Provides-Extra: docs
+Requires-Dist: sphinx<9,>=8.1; extra == "docs"
+Requires-Dist: furo<2026,>=2025.9; extra == "docs"
+Requires-Dist: myst-parser<5,>=4.0; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints<4,>=3.0; extra == "docs"
+Requires-Dist: sphinx-togglebutton<1,>=0.3; extra == "docs"
+Requires-Dist: sphinx-design<0.7,>=0.6; extra == "docs"
+Provides-Extra: build
+Requires-Dist: build<2,>=1.3; extra == "build"
+Requires-Dist: twine<7,>=6.2; extra == "build"
+Provides-Extra: tox
+Requires-Dist: tox<5,>=4.31; extra == "tox"
+Provides-Extra: infra-tools
+Requires-Dist: awscli-local<1,>=0.22; extra == "infra-tools"
+Provides-Extra: textual
+Requires-Dist: textual<7,>=6.3; extra == "textual"
+Provides-Extra: all
+Requires-Dist: pytest<9,>=8.4; extra == "all"
+Requires-Dist: pytest-cov<8,>=7.0; extra == "all"
+Requires-Dist: pytest-asyncio<2,>=1.2; extra == "all"
+Requires-Dist: ruff<1,>=0.14; extra == "all"
+Requires-Dist: mypy<2,>=1.18; extra == "all"
+Requires-Dist: types-PyYAML<7,>=6.0; extra == "all"
+Requires-Dist: sphinx<9,>=8.1; extra == "all"
+Requires-Dist: furo<2026,>=2025.9; extra == "all"
+Requires-Dist: myst-parser<5,>=4.0; extra == "all"
+Requires-Dist: sphinx-autodoc-typehints<4,>=3.0; extra == "all"
+Requires-Dist: sphinx-togglebutton<1,>=0.3; extra == "all"
+Requires-Dist: sphinx-design<0.7,>=0.6; extra == "all"
+Requires-Dist: build<2,>=1.3; extra == "all"
+Requires-Dist: twine<7,>=6.2; extra == "all"
+Requires-Dist: tox<5,>=4.31; extra == "all"
+Requires-Dist: pre-commit<5,>=4.0; extra == "all"
+Requires-Dist: boto3<2,>=1.35; extra == "all"
+Requires-Dist: awscli-local<1,>=0.22; extra == "all"
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/KaminoU/kstlib/main/assets/kstlib.svg" alt="Kstlib Logo" width="420">
+</p>
+
+<p align="center">
+  <strong>Config-driven Python toolkit for resilient applications</strong>
+</p>
+
+<p align="center">
+  <a href="https://github.com/KaminoU/kstlib/actions/workflows/ci.yml"><img src="https://github.com/KaminoU/kstlib/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
+  <a href="https://kstlib.readthedocs.io/"><img src="https://img.shields.io/badge/docs-RTD-blue" alt="Documentation"></a>
+  <a href="https://pypi.org/project/kstlib/"><img src="https://img.shields.io/pypi/v/kstlib?color=blue" alt="PyPI"></a>
+  <img src="https://img.shields.io/badge/python-≥3.10-blue" alt="Python">
+  <a href="https://github.com/KaminoU/kstlib/blob/main/LICENSE.md"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a>
+</p>
+
+---
+
+**kstlib** is a personal Python toolkit built over 7 years of learning and experimentation.
+
+It started as a way to explore Python best practices, evolved into utilities for personal automation,
+and now serves as the foundation for study projects in algorithmic trading and market analysis.
+
+The focus has always been on building **resilient, secure, and performant** systems.
+
+> **Note**: Everything works via Python, but since kstlib is heavily config-driven,
+> the [Examples Gallery](https://kstlib.readthedocs.io/en/latest/examples.html) showcases
+> a YAML-first approach.
+
+## Core Modules
+
+| Module | Purpose |
+|--------|---------|
+| **config** | Cascading config files, includes, SOPS encryption, Box access |
+| **secrets** | Multi-provider resolver (env, keyring, SOPS, KMS) with guardrails |
+| **logging** | Rich console, rotating files, TRACE level, structlog integration |
+| **auth** | OIDC/OAuth2 with PKCE, token storage, auto-refresh |
+| **mail** | Jinja templates, transports (SMTP, Gmail API, Resend) |
+| **alerts** | Multi-channel (Slack, Email), throttling, severity levels |
+| **websocket** | Resilient connections, auto-reconnect, heartbeat, watchdog |
+| **rapi** | Config-driven REST client with HMAC signing |
+| **monitoring** | Collectors + Jinja rendering + delivery (file, mail) |
+| **resilience** | Circuit breaker, rate limiter, graceful shutdown |
+| **ops** | Session manager (tmux), containers (Docker/Podman) |
+| **helpers** | TimeTrigger, formatting, secure delete, validators |
+
+## Quick Start
+
+### Installation
+
+```bash
+pip install kstlib
+```
+
+### Basic Usage
+
+```python
+from kstlib.config import load_from_file
+from kstlib import cache
+
+config = load_from_file("config.yml")
+
+@cache(ttl=300)
+def expensive_computation(x: int) -> int:
+    return x ** 2
+
+result = expensive_computation(5)
+```
+
+### Minimal Configuration
+
+```yaml
+app:
+  name: "My Application"
+  debug: true
+
+database:
+  host: "localhost"
+  port: 5432
+```
+
+## Documentation
+
+Full documentation available at **[kstlib.readthedocs.io](https://kstlib.readthedocs.io/)**
+
+- [Features Guide](https://kstlib.readthedocs.io/en/latest/features/index.html)
+- [Examples Gallery](https://kstlib.readthedocs.io/en/latest/examples.html)
+- [API Reference](https://kstlib.readthedocs.io/en/latest/api/index.html)
+- [Development Guide](https://kstlib.readthedocs.io/en/latest/development/index.html)
+
+## Installation Options
+
+```bash
+# Standard install
+pip install kstlib
+
+# With uv (faster)
+uv pip install kstlib
+
+# Development install
+pip install "kstlib[dev]"
+
+# All extras
+pip install "kstlib[all]"
+
+# From GitHub (latest)
+pip install "git+https://github.com/KaminoU/kstlib.git"
+```
+
+## License
+
+MIT License - Copyright 2025 Michel TRUONG
+
+See [LICENSE](LICENSE.md) for full text.