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

kstlib/metrics/exceptions.py

@@ -0,0 +1,14 @@
+"""Exceptions for the metrics module."""
+
+__all__ = ["MetricsError"]
+
+
+class MetricsError(Exception):
+    """Base exception for metrics-related errors.
+
+    Examples:
+        >>> raise MetricsError("Something went wrong")
+        Traceback (most recent call last):
+            ...
+        kstlib.metrics.exceptions.MetricsError: Something went wrong
+    """

kstlib/monitoring/__init__.py

@@ -0,0 +1,116 @@
+"""HTML monitoring render types for dashboards and email reports.
+
+This module provides five render types that produce HTML output suitable
+for both browser dashboards (CSS classes) and email reports (inline CSS).
+
+Render types:
+
+- **StatusCell**: Colored ``<span>`` badge for UP/DOWN/DEGRADED indicators.
+- **MonitorTable**: Striped ``<table>`` with typed headers and row validation.
+- **MonitorKV**: Two-column ``<dl>`` grid for key-value stat panels.
+- **MonitorList**: ``<ul>``/``<ol>`` for event logs and alert lists.
+- **MonitorMetric**: Hero-number ``<div>`` for KPI display (P&L, uptime).
+- **MonitorImage**: Base64 ``<img>`` for embedded logos and icons.
+
+All render types implement ``render(*, inline_css: bool = False) -> str``:
+
+- ``inline_css=False``: CSS class references (``.status-ok``, ``.monitor-table``).
+- ``inline_css=True``: Inline ``style`` attributes for email compatibility.
+
+Examples:
+    Basic status badge:
+
+    >>> from kstlib.monitoring import StatusCell, StatusLevel
+    >>> cell = StatusCell("UP", StatusLevel.OK)
+    >>> cell.render()
+    '<span class="status-ok">UP</span>'
+
+    Table with status cells:
+
+    >>> from kstlib.monitoring import MonitorTable
+    >>> t = MonitorTable(headers=["Service", "Status"])
+    >>> t.add_row(["API", StatusCell("OK", StatusLevel.OK)])
+    >>> "<table" in t.render()
+    True
+"""
+
+from __future__ import annotations
+
+from kstlib.monitoring._styles import get_css_classes
+from kstlib.monitoring.cell import StatusCell
+from kstlib.monitoring.config import (
+    CollectorConfig,
+    MonitoringConfig,
+    MonitoringConfigCollectorError,
+    MonitoringConfigFileNotFoundError,
+    MonitoringConfigFormatError,
+    create_services_from_directory,
+    discover_monitoring_configs,
+    load_monitoring_config,
+)
+from kstlib.monitoring.delivery import (
+    DeliveryBackend,
+    DeliveryConfigError,
+    DeliveryError,
+    DeliveryIOError,
+    DeliveryResult,
+    FileDelivery,
+    FileDeliveryConfig,
+    MailDelivery,
+    MailDeliveryConfig,
+)
+from kstlib.monitoring.exceptions import (
+    CollectorError,
+    MonitoringConfigError,
+    MonitoringError,
+    RenderError,
+)
+from kstlib.monitoring.image import MonitorImage
+from kstlib.monitoring.kv import MonitorKV
+from kstlib.monitoring.list import MonitorList
+from kstlib.monitoring.metric import MonitorMetric
+from kstlib.monitoring.monitoring import Monitoring
+from kstlib.monitoring.renderer import create_environment, render_html, render_template
+from kstlib.monitoring.service import MonitoringResult, MonitoringService
+from kstlib.monitoring.table import MonitorTable
+from kstlib.monitoring.types import CellValue, Renderable, StatusLevel
+
+__all__ = [
+    "CellValue",
+    "CollectorConfig",
+    "CollectorError",
+    "DeliveryBackend",
+    "DeliveryConfigError",
+    "DeliveryError",
+    "DeliveryIOError",
+    "DeliveryResult",
+    "FileDelivery",
+    "FileDeliveryConfig",
+    "MailDelivery",
+    "MailDeliveryConfig",
+    "MonitorImage",
+    "MonitorKV",
+    "MonitorList",
+    "MonitorMetric",
+    "MonitorTable",
+    "Monitoring",
+    "MonitoringConfig",
+    "MonitoringConfigCollectorError",
+    "MonitoringConfigError",
+    "MonitoringConfigFileNotFoundError",
+    "MonitoringConfigFormatError",
+    "MonitoringError",
+    "MonitoringResult",
+    "MonitoringService",
+    "RenderError",
+    "Renderable",
+    "StatusCell",
+    "StatusLevel",
+    "create_environment",
+    "create_services_from_directory",
+    "discover_monitoring_configs",
+    "get_css_classes",
+    "load_monitoring_config",
+    "render_html",
+    "render_template",
+]

kstlib/monitoring/_styles.py

@@ -0,0 +1,163 @@
+"""Centralized colors and CSS helpers for monitoring HTML rendering.
+
+All colors, CSS class names, and inline style strings are defined here
+to ensure visual consistency across all render types.
+"""
+
+from __future__ import annotations
+
+from kstlib.monitoring.types import StatusLevel
+
+# ---------------------------------------------------------------------------
+# Color palette
+# ---------------------------------------------------------------------------
+
+#: Mapping of status levels to their hex color codes.
+STATUS_COLORS: dict[StatusLevel, str] = {
+    StatusLevel.OK: "#16A085",
+    StatusLevel.WARNING: "#F1C40F",
+    StatusLevel.ERROR: "#E85A4F",
+    StatusLevel.CRITICAL: "#c0392b",
+}
+
+#: Mapping of status levels to their text color (for contrast).
+STATUS_TEXT_COLORS: dict[StatusLevel, str] = {
+    StatusLevel.OK: "#ffffff",
+    StatusLevel.WARNING: "#2c3e50",
+    StatusLevel.ERROR: "#ffffff",
+    StatusLevel.CRITICAL: "#ffffff",
+}
+
+# ---------------------------------------------------------------------------
+# CSS class names
+# ---------------------------------------------------------------------------
+
+#: Mapping of status levels to their CSS class names.
+STATUS_CSS_CLASSES: dict[StatusLevel, str] = {
+    StatusLevel.OK: "status-ok",
+    StatusLevel.WARNING: "status-warning",
+    StatusLevel.ERROR: "status-error",
+    StatusLevel.CRITICAL: "status-critical",
+}
+
+# ---------------------------------------------------------------------------
+# Table styling constants
+# ---------------------------------------------------------------------------
+
+TABLE_BORDER_COLOR = "#ddd"
+TABLE_HEADER_BG = "#2c3e50"
+TABLE_HEADER_TEXT = "#ffffff"
+TABLE_ROW_BG = "#ffffff"
+TABLE_ROW_TEXT = "#2c3e50"
+TABLE_STRIPE_BG = "#f0f0f0"
+TABLE_FONT_FAMILY = "Consolas, Monaco, 'Courier New', monospace"
+
+# ---------------------------------------------------------------------------
+# Metric styling constants
+# ---------------------------------------------------------------------------
+
+METRIC_FONT_SIZE = "2.5em"
+METRIC_LABEL_COLOR = "#7f8c8d"
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def inline_badge_style(level: StatusLevel) -> str:
+    """Return an inline CSS style string for a status badge.
+
+    Args:
+        level: The status severity level.
+
+    Returns:
+        CSS style string suitable for a ``style`` attribute.
+
+    Examples:
+        >>> from kstlib.monitoring._styles import inline_badge_style
+        >>> from kstlib.monitoring.types import StatusLevel
+        >>> "background" in inline_badge_style(StatusLevel.OK)
+        True
+    """
+    bg = STATUS_COLORS[level]
+    fg = STATUS_TEXT_COLORS[level]
+    return f"background:{bg};color:{fg};padding:2px 8px;border-radius:4px;font-weight:bold;font-size:0.85em"
+
+
+def get_css_classes() -> str:
+    """Return a ``<style>`` block with all monitoring CSS classes.
+
+    This should be included once in the ``<head>`` of an HTML document
+    when using class-based rendering (``inline_css=False``).
+
+    Returns:
+        Complete ``<style>`` element as a string.
+
+    Examples:
+        >>> from kstlib.monitoring._styles import get_css_classes
+        >>> css = get_css_classes()
+        >>> "<style>" in css
+        True
+        >>> ".status-ok" in css
+        True
+    """
+    rules: list[str] = []
+
+    # Status badge classes
+    for level in StatusLevel:
+        cls = STATUS_CSS_CLASSES[level]
+        bg = STATUS_COLORS[level]
+        fg = STATUS_TEXT_COLORS[level]
+        rules.append(
+            f".{cls} {{"
+            f" background:{bg}; color:{fg};"
+            f" padding:2px 8px; border-radius:4px;"
+            f" font-weight:bold; font-size:0.85em;"
+            f" }}"
+        )
+
+    # Monitor table
+    rules.append(
+        f".monitor-table {{"
+        f" border-collapse:collapse; width:100%; font-family:{TABLE_FONT_FAMILY};"
+        f" background:{TABLE_ROW_BG}; color:{TABLE_ROW_TEXT};"
+        f" }}"
+    )
+    rules.append(
+        f".monitor-table th {{"
+        f" background:{TABLE_HEADER_BG}; color:{TABLE_HEADER_TEXT};"
+        f" padding:8px 12px; text-align:left;"
+        f" }}"
+    )
+    rules.append(f".monitor-table td {{ padding:8px 12px; border-bottom:1px solid {TABLE_BORDER_COLOR}; }}")
+    rules.append(f".monitor-table tr:nth-child(even) {{ background:{TABLE_STRIPE_BG}; }}")
+
+    # Monitor KV
+    rules.append(".monitor-kv { display:grid; grid-template-columns:auto 1fr; gap:4px 12px; }")
+    rules.append(".monitor-kv dt { font-weight:bold; }")
+
+    # Monitor metric
+    rules.append(".monitor-metric { text-align:center; padding:12px; }")
+    rules.append(f".monitor-metric .metric-value {{ font-size:{METRIC_FONT_SIZE}; font-weight:bold; }}")
+    rules.append(f".monitor-metric .metric-label {{ color:{METRIC_LABEL_COLOR}; font-size:0.9em; }}")
+
+    body = "\n".join(rules)
+    return f"<style>\n{body}\n</style>"
+
+
+__all__ = [
+    "METRIC_FONT_SIZE",
+    "METRIC_LABEL_COLOR",
+    "STATUS_COLORS",
+    "STATUS_CSS_CLASSES",
+    "STATUS_TEXT_COLORS",
+    "TABLE_BORDER_COLOR",
+    "TABLE_FONT_FAMILY",
+    "TABLE_HEADER_BG",
+    "TABLE_HEADER_TEXT",
+    "TABLE_ROW_BG",
+    "TABLE_ROW_TEXT",
+    "TABLE_STRIPE_BG",
+    "get_css_classes",
+    "inline_badge_style",
+]

kstlib/monitoring/cell.py

@@ -0,0 +1,57 @@
+"""StatusCell render type for colored status badges.
+
+A ``StatusCell`` renders as a ``<span>`` badge with color coding based on
+the severity level (OK, WARNING, ERROR, CRITICAL).
+"""
+
+from __future__ import annotations
+
+import html
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from kstlib.monitoring._styles import STATUS_CSS_CLASSES, inline_badge_style
+
+if TYPE_CHECKING:
+    from kstlib.monitoring.types import StatusLevel
+
+
+@dataclass(frozen=True, slots=True)
+class StatusCell:
+    """A colored status badge rendered as an HTML ``<span>``.
+
+    Attributes:
+        label: Display text for the badge (e.g. "UP", "DOWN", "DEGRADED").
+        level: Severity level controlling badge color.
+
+    Examples:
+        >>> from kstlib.monitoring.cell import StatusCell
+        >>> from kstlib.monitoring.types import StatusLevel
+        >>> cell = StatusCell("UP", StatusLevel.OK)
+        >>> "<span" in cell.render()
+        True
+    """
+
+    label: str
+    level: StatusLevel
+
+    def render(self, *, inline_css: bool = False) -> str:
+        """Render the status badge as an HTML ``<span>``.
+
+        Args:
+            inline_css: If True, use inline styles instead of CSS classes.
+
+        Returns:
+            HTML ``<span>`` string.
+        """
+        escaped = html.escape(self.label)
+        if inline_css:
+            style = inline_badge_style(self.level)
+            return f'<span style="{style}">{escaped}</span>'
+        cls = STATUS_CSS_CLASSES[self.level]
+        return f'<span class="{cls}">{escaped}</span>'
+
+
+__all__ = [
+    "StatusCell",
+]