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

kstlib/__init__.py

@@ -1 +1,266 @@
-__version__ = "0.0.1a0"
+"""
+##################################################################################################    ###    ###    ####
+##################################################################################################    ###    ###    ####
+##                                                                                                                    ##
+##             ##################   .#######:     .######.     ##########################################             ##
+##             ##################..#########.   .#########.    ##########################################             ##
+##             ###           ########.         :###########:                                          ###             ##
+##             ###           ######.           .##########:.                                          ###             ##
+##             ###           ####.            .#########:.                                            ###             ##
+##             ###           ##.            .#######                                                  ###             ##
+##             ###           "            .######                                                     ###             ##
+##             ###                     .:######                                           ###############             ##
+##             ###                 .##########:.                .:#######.                ###############             ##
+##             ###               :########################################.               ###                         ##
+##             ###              :################# L I B ##################:              ###                         ##
+##             ###               .########################################.               ###                         ##
+##             ###                 :######:.                 ###########.                 ###                         ##
+##             ###                                         :######:.                      ###                         ##
+##             ###           .                           :######:.           .            ###                         ##
+##             ###           ##                       .:######.             ##            ###                         ##
+##             ###           ####                .:#########.              ###            ###                         ##
+##             ###           ######             :###########:              ###            ###                         ##
+##             ###           ########           :###########:              ###            ###                         ##
+##             ##################..##########.  ":#########"               ##################                         ##
+##             ##################  .#########:   ":######:"                ##################                         ##
+##                                                                                                                    ##
+###################################################################################################[ Michel TRUONG ]####
+########################################################################################################################
+kstlib package - PEP 562 lazy loading for fast imports.
+
+All public symbols are loaded lazily on first access.
+Import time target: < 100ms (from ~330ms with eager loading).
+"""
+
+# pylint: disable=global-statement,import-outside-toplevel,invalid-name
+
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING, Any
+
+# Public API exports (sorted alphabetically)
+__all__ = [
+    "ConfigCircularIncludeError",
+    "ConfigError",
+    "ConfigFileNotFoundError",
+    "ConfigFormatError",
+    "ConfigLoader",
+    "ConfigNotLoadedError",
+    "KstlibError",
+    "LogManager",
+    "MonitoringError",
+    "PanelManager",
+    "PanelRenderingError",
+    "alerts",
+    "app",
+    "auth",
+    "cache",
+    "clear_config",
+    "db",
+    "get_config",
+    "install_rich_traceback",
+    "load_config",
+    "load_from_env",
+    "load_from_file",
+    "mail",
+    "metrics",
+    "monitoring",
+    "rapi",
+    "require_config",
+    "resilience",
+    "secrets",
+    "secure",
+    "ui",
+    "utils",
+    "websocket",
+]
+
+# Lazy-loaded submodules
+_SUBMODULES: frozenset[str] = frozenset(
+    {
+        "alerts",
+        "app",
+        "auth",
+        "cache",
+        "db",
+        "mail",
+        "metrics",
+        "monitoring",
+        "rapi",
+        "resilience",
+        "secrets",
+        "secure",
+        "ui",
+        "utils",
+        "websocket",
+    }
+)
+
+# Mapping of attribute names to their import paths
+_LAZY_IMPORTS: dict[str, tuple[str, str]] = {
+    # Config exceptions and classes
+    "ConfigCircularIncludeError": ("kstlib.config", "ConfigCircularIncludeError"),
+    "ConfigError": ("kstlib.config", "ConfigError"),
+    "ConfigFileNotFoundError": ("kstlib.config", "ConfigFileNotFoundError"),
+    "ConfigFormatError": ("kstlib.config", "ConfigFormatError"),
+    "ConfigLoader": ("kstlib.config", "ConfigLoader"),
+    "ConfigNotLoadedError": ("kstlib.config.exceptions", "ConfigNotLoadedError"),
+    "KstlibError": ("kstlib.config", "KstlibError"),
+    # Config functional API
+    "clear_config": ("kstlib.config.loader", "clear_config"),
+    "get_config": ("kstlib.config.loader", "get_config"),
+    "load_config": ("kstlib.config.loader", "load_config"),
+    "load_from_env": ("kstlib.config.loader", "load_from_env"),
+    "load_from_file": ("kstlib.config.loader", "load_from_file"),
+    "require_config": ("kstlib.config.loader", "require_config"),
+    # Logging
+    "LogManager": ("kstlib.logging", "LogManager"),
+    # Monitoring
+    "MonitoringError": ("kstlib.monitoring", "MonitoringError"),
+    # UI
+    "PanelManager": ("kstlib.ui", "PanelManager"),
+    "PanelRenderingError": ("kstlib.ui", "PanelRenderingError"),
+}
+
+# Cache for loaded modules/attributes
+_loaded: dict[str, Any] = {}
+
+# Flag to track if rich traceback has been installed
+_traceback_installed: bool = False
+
+
+def install_rich_traceback() -> None:
+    """Install Rich enhanced tracebacks.
+
+    Call this explicitly if you want enhanced tracebacks. By default, tracebacks
+    are not installed to keep import time fast.
+
+    To auto-install on import (legacy behavior), set KSTLIB_TRACEBACK=1:
+
+    - Bash/zsh: export KSTLIB_TRACEBACK=1
+    - PowerShell: $env:KSTLIB_TRACEBACK = "1"
+    """
+    global _traceback_installed
+    if _traceback_installed:
+        return
+
+    import shutil
+
+    from rich.traceback import install
+
+    terminal_width = shutil.get_terminal_size(fallback=(120, 20)).columns
+    install(
+        show_locals=True,
+        word_wrap=True,
+        width=terminal_width,
+        extra_lines=7,
+    )
+    _traceback_installed = True
+
+
+def __getattr__(name: str) -> Any:
+    """Lazily load modules and attributes on first access (PEP 562)."""
+    # Check cache first
+    if name in _loaded:
+        return _loaded[name]
+
+    # Handle submodules
+    if name in _SUBMODULES:
+        if name == "app":
+            # Import the Typer app object, not the module
+            module = importlib.import_module("kstlib.cli")
+            _loaded[name] = module.app
+            return module.app
+        if name == "cache":
+            module = importlib.import_module("kstlib.cache")
+            _loaded[name] = module.cache
+            return module.cache
+        module = importlib.import_module(f"kstlib.{name}")
+        _loaded[name] = module
+        return module
+
+    # Handle lazy imports
+    if name in _LAZY_IMPORTS:
+        module_path, attr_name = _LAZY_IMPORTS[name]
+        try:
+            module = importlib.import_module(module_path)
+            attr = getattr(module, attr_name)
+            _loaded[name] = attr
+            return attr
+        except (ImportError, AttributeError):
+            # ConfigNotLoadedError might not exist in minimal installs
+            if name == "ConfigNotLoadedError":
+                _loaded[name] = None
+                return None
+            raise
+
+    raise AttributeError(f"module 'kstlib' has no attribute {name!r}")
+
+
+# Auto-install rich traceback if KSTLIB_TRACEBACK=1 (opt-in for fast imports)
+# Default changed from "1" to "0" for metricsormance - users must opt-in now
+if TYPE_CHECKING:
+    # For static analysis - provide type hints for lazy-loaded symbols
+    # pylint: disable=useless-import-alias
+    from kstlib import alerts as alerts
+    from kstlib import auth as auth
+    from kstlib import db as db
+    from kstlib import mail as mail
+    from kstlib import metrics as metrics
+    from kstlib import monitoring as monitoring
+    from kstlib import rapi as rapi
+    from kstlib import resilience as resilience
+    from kstlib import secrets as secrets
+    from kstlib import secure as secure
+    from kstlib import ui as ui
+    from kstlib import utils as utils
+    from kstlib import websocket as websocket
+    from kstlib.cache import cache as cache
+    from kstlib.cli import app as app  # Typer app object
+    from kstlib.config import (
+        ConfigCircularIncludeError as ConfigCircularIncludeError,
+    )
+    from kstlib.config import (
+        ConfigError as ConfigError,
+    )
+    from kstlib.config import (
+        ConfigFileNotFoundError as ConfigFileNotFoundError,
+    )
+    from kstlib.config import (
+        ConfigFormatError as ConfigFormatError,
+    )
+    from kstlib.config import (
+        ConfigLoader as ConfigLoader,
+    )
+    from kstlib.config import (
+        KstlibError as KstlibError,
+    )
+    from kstlib.config.exceptions import ConfigNotLoadedError as ConfigNotLoadedError
+    from kstlib.config.loader import (
+        clear_config as clear_config,
+    )
+    from kstlib.config.loader import (
+        get_config as get_config,
+    )
+    from kstlib.config.loader import (
+        load_config as load_config,
+    )
+    from kstlib.config.loader import (
+        load_from_env as load_from_env,
+    )
+    from kstlib.config.loader import (
+        load_from_file as load_from_file,
+    )
+    from kstlib.config.loader import (
+        require_config as require_config,
+    )
+    from kstlib.logging import LogManager as LogManager
+    from kstlib.monitoring import MonitoringError as MonitoringError
+    from kstlib.ui import PanelManager as PanelManager
+    from kstlib.ui import PanelRenderingError as PanelRenderingError
+else:
+    import os as _os
+
+    if _os.getenv("KSTLIB_TRACEBACK", "0") == "1":
+        install_rich_traceback()

kstlib/__main__.py

@@ -0,0 +1,16 @@
+"""Entry point for kstlib CLI application.
+
+This module serves as the entry point when kstlib is invoked as a module
+(python -m kstlib) or through the installed console script.
+"""
+
+from kstlib.cli import app
+
+
+def main() -> None:
+    """Run the kstlib CLI application."""
+    app()
+
+
+if __name__ == "__main__":
+    main()

kstlib/alerts/__init__.py

@@ -0,0 +1,110 @@
+"""Multi-channel alerting module with Slack and Email support.
+
+This module provides a flexible alerting system for sending notifications
+to multiple channels (Slack, Email) with level-based filtering and
+rate limiting.
+
+Key components:
+
+- :class:`AlertManager`: Orchestrates multi-channel delivery
+- :class:`AlertMessage`: The alert payload with title, body, and level
+- :class:`AlertLevel`: Severity levels (INFO, WARNING, CRITICAL)
+- :class:`AlertThrottle`: Rate limiting for alert floods
+
+Channels:
+
+- :class:`SlackChannel`: Slack webhook delivery
+- :class:`EmailChannel`: Email delivery via kstlib.mail transports
+
+Examples:
+    Basic Slack alert::
+
+        from kstlib.alerts import AlertManager, AlertMessage, AlertLevel
+        from kstlib.alerts.channels import SlackChannel
+
+        channel = SlackChannel(
+            webhook_url="https://hooks.slack.com/services/T.../B.../xxx"
+        )
+
+        manager = AlertManager().add_channel(channel)
+
+        alert = AlertMessage(
+            title="Deployment Complete",
+            body="Version 2.1.0 deployed to production",
+            level=AlertLevel.INFO,
+        )
+
+        results = await manager.send(alert)
+
+    Multi-channel with level filtering::
+
+        from kstlib.alerts.channels import EmailChannel
+        from kstlib.mail.transports import SMTPTransport
+
+        smtp = SMTPTransport(host="smtp.example.com", port=587)
+        email_channel = EmailChannel(
+            transport=smtp,
+            sender="alerts@example.com",
+            recipients=["oncall@example.com"],
+        )
+
+        manager = (
+            AlertManager()
+            .add_channel(slack_channel, min_level=AlertLevel.WARNING)
+            .add_channel(email_channel, min_level=AlertLevel.CRITICAL)
+        )
+
+        # This goes to Slack only (WARNING level)
+        await manager.send(AlertMessage(
+            title="High Memory",
+            body="Memory at 85%",
+            level=AlertLevel.WARNING,
+        ))
+
+        # This goes to both Slack and Email (CRITICAL level)
+        await manager.send(AlertMessage(
+            title="Server Down",
+            body="API server not responding",
+            level=AlertLevel.CRITICAL,
+        ))
+
+    With rate limiting::
+
+        from kstlib.alerts.throttle import AlertThrottle
+
+        throttle = AlertThrottle(rate=10, per=60.0)  # 10 per minute
+
+        manager = AlertManager().add_channel(
+            slack_channel,
+            throttle=throttle,
+        )
+
+    From configuration::
+
+        manager = AlertManager.from_config(
+            config=app_config["alerts"],
+            credential_resolver=resolver,
+        )
+"""
+
+from kstlib.alerts.exceptions import (
+    AlertConfigurationError,
+    AlertDeliveryError,
+    AlertError,
+    AlertThrottledError,
+)
+from kstlib.alerts.manager import AlertManager
+from kstlib.alerts.models import AlertLevel, AlertMessage, AlertResult
+from kstlib.alerts.throttle import AlertThrottle
+
+__all__ = [
+    "AlertConfigurationError",
+    "AlertDeliveryError",
+    "AlertError",
+    "AlertLevel",
+    "AlertManager",
+    "AlertMessage",
+    "AlertResult",
+    "AlertThrottle",
+    "AlertThrottledError",
+]

kstlib/alerts/channels/__init__.py

@@ -0,0 +1,36 @@
+"""Alert channel implementations.
+
+Provides both sync and async channel interfaces for different alert
+delivery backends (Slack, Email, etc.).
+
+Examples:
+    Using SlackChannel::
+
+        from kstlib.alerts.channels import SlackChannel
+
+        channel = SlackChannel(webhook_url="https://hooks.slack.com/...")
+        await channel.send(alert)
+
+    Using EmailChannel with existing mail transport::
+
+        from kstlib.alerts.channels import EmailChannel
+        from kstlib.mail.transports import SMTPTransport
+
+        transport = SMTPTransport(host="smtp.example.com", port=587)
+        channel = EmailChannel(
+            transport=transport,
+            sender="alerts@example.com",
+            recipients=["oncall@example.com"],
+        )
+"""
+
+from kstlib.alerts.channels.base import AlertChannel, AsyncAlertChannel
+from kstlib.alerts.channels.email import EmailChannel
+from kstlib.alerts.channels.slack import SlackChannel
+
+__all__ = [
+    "AlertChannel",
+    "AsyncAlertChannel",
+    "EmailChannel",
+    "SlackChannel",
+]

kstlib/alerts/channels/base.py

@@ -0,0 +1,197 @@
+"""Abstract base classes for alert channels.
+
+Provides both sync and async channel interfaces following the same
+pattern as :mod:`kstlib.mail.transport`.
+
+Examples:
+    Implementing a sync channel::
+
+        class WebhookChannel(AlertChannel):
+            @property
+            def name(self) -> str:
+                return "webhook"
+
+            def send(self, alert: AlertMessage) -> AlertResult:
+                # Send via HTTP POST
+                return AlertResult(channel=self.name, success=True)
+
+    Implementing an async channel::
+
+        class AsyncWebhookChannel(AsyncAlertChannel):
+            @property
+            def name(self) -> str:
+                return "async_webhook"
+
+            async def send(self, alert: AlertMessage) -> AlertResult:
+                async with httpx.AsyncClient() as client:
+                    # Send via HTTP POST
+                    pass
+                return AlertResult(channel=self.name, success=True)
+"""
+
+from __future__ import annotations
+
+import asyncio
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from concurrent.futures import ThreadPoolExecutor
+
+    from kstlib.alerts.models import AlertMessage, AlertResult
+
+
+class AlertChannel(ABC):
+    """Abstract sync channel for delivering alerts.
+
+    Subclass this for synchronous alert delivery implementations.
+
+    Examples:
+        Implementing a custom sync channel::
+
+            class LogChannel(AlertChannel):
+                @property
+                def name(self) -> str:
+                    return "log"
+
+                def send(self, alert: AlertMessage) -> AlertResult:
+                    print(f"[{alert.level.name}] {alert.title}")
+                    return AlertResult(channel=self.name, success=True)
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Return the unique name of this channel.
+
+        Used for logging, metrics, and result identification.
+        """
+
+    @abstractmethod
+    def send(self, alert: AlertMessage) -> AlertResult:
+        """Deliver the alert via this channel.
+
+        Args:
+            alert: The alert message to deliver.
+
+        Returns:
+            AlertResult with delivery status.
+
+        Raises:
+            AlertDeliveryError: If delivery fails.
+        """
+
+
+class AsyncAlertChannel(ABC):
+    """Abstract async channel for delivering alerts.
+
+    Subclass this for asynchronous alert delivery implementations
+    that use async HTTP clients or other async I/O.
+
+    Examples:
+        Implementing a custom async channel::
+
+            class SlackChannel(AsyncAlertChannel):
+                @property
+                def name(self) -> str:
+                    return "slack"
+
+                async def send(self, alert: AlertMessage) -> AlertResult:
+                    async with httpx.AsyncClient() as client:
+                        await client.post(...)
+                    return AlertResult(channel=self.name, success=True)
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Return the unique name of this channel.
+
+        Used for logging, metrics, and result identification.
+        """
+
+    @abstractmethod
+    async def send(self, alert: AlertMessage) -> AlertResult:
+        """Deliver the alert asynchronously via this channel.
+
+        Args:
+            alert: The alert message to deliver.
+
+        Returns:
+            AlertResult with delivery status.
+
+        Raises:
+            AlertDeliveryError: If delivery fails.
+        """
+
+
+class AsyncChannelWrapper(AsyncAlertChannel):
+    """Wrap a sync channel for async usage.
+
+    Executes the sync channel's send method in a thread pool executor
+    to avoid blocking the event loop. Follows the same pattern as
+    :class:`kstlib.mail.transport.AsyncTransportWrapper`.
+
+    Args:
+        channel: The sync channel to wrap.
+        executor: Optional thread pool executor. If None, uses the default.
+
+    Examples:
+        Wrapping a sync channel::
+
+            sync_channel = LogChannel()
+            async_channel = AsyncChannelWrapper(sync_channel)
+
+            # Now usable in async context
+            await async_channel.send(alert)
+    """
+
+    def __init__(
+        self,
+        channel: AlertChannel,
+        *,
+        executor: ThreadPoolExecutor | None = None,
+    ) -> None:
+        """Initialize the async wrapper.
+
+        Args:
+            channel: The sync channel to wrap.
+            executor: Optional custom thread pool executor.
+        """
+        self._channel = channel
+        self._executor = executor
+
+    @property
+    def name(self) -> str:
+        """Return the name of the wrapped channel."""
+        return self._channel.name
+
+    @property
+    def channel(self) -> AlertChannel:
+        """Return the wrapped sync channel."""
+        return self._channel
+
+    async def send(self, alert: AlertMessage) -> AlertResult:
+        """Send alert asynchronously via the wrapped channel.
+
+        Runs the sync channel's send method in a thread pool to avoid
+        blocking the async event loop.
+
+        Args:
+            alert: The alert message to send.
+
+        Returns:
+            AlertResult from the wrapped channel.
+
+        Raises:
+            AlertDeliveryError: If the underlying channel fails.
+        """
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(
+            self._executor,
+            self._channel.send,
+            alert,
+        )
+
+
+__all__ = ["AlertChannel", "AsyncAlertChannel", "AsyncChannelWrapper"]