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

kstlib/monitoring/image.py

@@ -0,0 +1,220 @@
+r"""MonitorImage render type for embedded images.
+
+A ``MonitorImage`` renders as an HTML ``<img>`` tag with a base64-encoded
+``data:`` URI, suitable for embedding logos and icons in email templates
+where external image references are typically blocked.
+
+Examples:
+    >>> from kstlib.monitoring.image import MonitorImage
+    >>> img = MonitorImage(b"\x89PNG\r\n\x1a\n" + b"\x00" * 50, alt="Logo")
+    >>> "data:image/png;base64," in img.render()
+    True
+"""
+
+from __future__ import annotations
+
+import base64
+import html
+import re
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from kstlib.monitoring.exceptions import RenderError
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+# ---------------------------------------------------------------------------
+# Image format detection and limits
+# ---------------------------------------------------------------------------
+
+#: Maximum allowed image size in bytes (512 KB).
+IMAGE_MAX_BYTES: int = 512 * 1024
+
+#: Supported image MIME types with their magic byte signatures.
+#: Each entry maps a MIME type to a tuple of possible magic byte prefixes.
+_MAGIC_SIGNATURES: dict[str, tuple[bytes, ...]] = {
+    "image/png": (b"\x89PNG\r\n\x1a\n",),
+    "image/jpeg": (b"\xff\xd8\xff",),
+    "image/gif": (b"GIF87a", b"GIF89a"),
+    "image/webp": (b"RIFF",),  # RIFF....WEBP (bytes 8-11 checked separately)
+    "image/svg+xml": (),  # detected by text heuristic, not magic bytes
+}
+
+#: Allowed MIME types for images.
+ALLOWED_MIME_TYPES: frozenset[str] = frozenset(_MAGIC_SIGNATURES)
+
+#: Pattern matching dangerous SVG content (script tags, event handlers).
+_SVG_DANGEROUS_PATTERN: re.Pattern[str] = re.compile(
+    r"<script|on\w+\s*=",
+    re.IGNORECASE,
+)
+
+
+def _detect_mime_type(data: bytes) -> str | None:
+    """Detect image MIME type from magic bytes.
+
+    Args:
+        data: Raw image bytes (at least the first 12 bytes).
+
+    Returns:
+        MIME type string if recognized, or None.
+    """
+    for mime, signatures in _MAGIC_SIGNATURES.items():
+        for sig in signatures:
+            if data.startswith(sig):
+                if mime == "image/webp" and data[8:12] != b"WEBP":
+                    continue
+                return mime
+
+    # SVG heuristic: XML-like text containing <svg
+    if len(data) > 4 and data[:4] != b"\x00\x00\x00\x00":
+        try:
+            head = data[:1024].decode("utf-8", errors="strict")
+        except UnicodeDecodeError:
+            return None
+        if "<svg" in head.lower():
+            return "image/svg+xml"
+
+    return None
+
+
+def _validate_svg(data: bytes) -> None:
+    """Validate SVG content for dangerous patterns.
+
+    Args:
+        data: Raw SVG bytes.
+
+    Raises:
+        RenderError: If dangerous content is detected.
+    """
+    try:
+        text = data.decode("utf-8")
+    except UnicodeDecodeError:
+        msg = "SVG content is not valid UTF-8"
+        raise RenderError(msg)  # noqa: B904 - intentional chain break for clean message
+    if _SVG_DANGEROUS_PATTERN.search(text):
+        msg = "SVG contains dangerous content (script or event handler)"
+        raise RenderError(msg)
+
+
+# ---------------------------------------------------------------------------
+# MonitorImage
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class MonitorImage:
+    r"""An image rendered as an HTML ``<img>`` with a base64 data URI.
+
+    The image data can be provided directly as ``bytes`` or loaded from
+    a file ``path``. Exactly one of ``data`` or ``path`` must be given.
+
+    Attributes:
+        data: Raw image bytes. Mutually exclusive with ``path``.
+        path: Path to an image file. Mutually exclusive with ``data``.
+        alt: Alt text for the ``<img>`` tag (always HTML-escaped).
+        width: Optional width attribute (pixels).
+        height: Optional height attribute (pixels).
+
+    Raises:
+        RenderError: If both or neither of ``data``/``path`` are given,
+            the image exceeds size limits, or the format is unsupported.
+
+    Examples:
+        >>> from kstlib.monitoring.image import MonitorImage
+        >>> img = MonitorImage(b"\x89PNG\r\n\x1a\n" + b"\x00" * 50, alt="Logo")
+        >>> "<img" in img.render()
+        True
+    """
+
+    data: bytes | None = None
+    path: Path | None = None
+    alt: str = ""
+    width: int | None = None
+    height: int | None = None
+
+    def __post_init__(self) -> None:
+        """Validate inputs at construction time."""
+        if self.data is not None and self.path is not None:
+            msg = "Provide either data or path, not both"
+            raise RenderError(msg)
+        if self.data is None and self.path is None:
+            msg = "Provide either data or path"
+            raise RenderError(msg)
+        if self.width is not None and self.width <= 0:
+            msg = f"width must be positive, got {self.width}"
+            raise RenderError(msg)
+        if self.height is not None and self.height <= 0:
+            msg = f"height must be positive, got {self.height}"
+            raise RenderError(msg)
+
+    def _load_data(self) -> bytes:
+        """Load and validate image bytes."""
+        if self.data is not None:
+            raw = self.data
+        else:
+            assert self.path is not None  # guaranteed by __post_init__
+            if not self.path.is_file():
+                msg = f"Image file not found: {self.path}"
+                raise RenderError(msg)
+            raw = self.path.read_bytes()
+
+        if len(raw) > IMAGE_MAX_BYTES:
+            size_kb = len(raw) // 1024
+            limit_kb = IMAGE_MAX_BYTES // 1024
+            msg = f"Image too large: {size_kb} KB (limit: {limit_kb} KB)"
+            raise RenderError(msg)
+
+        if len(raw) < 4:
+            msg = "Image data too small to be valid"
+            raise RenderError(msg)
+
+        return raw
+
+    def render(self, *, inline_css: bool = False) -> str:
+        """Render the image as an HTML ``<img>`` with a data URI.
+
+        The ``inline_css`` parameter is accepted for protocol conformance
+        but has no effect on image rendering (images are always inline).
+
+        Args:
+            inline_css: Accepted for Renderable protocol compatibility.
+
+        Returns:
+            HTML ``<img>`` string with base64 data URI.
+
+        Raises:
+            RenderError: If the image cannot be loaded, exceeds size
+                limits, has an unsupported format, or (for SVG) contains
+                dangerous content.
+        """
+        _ = inline_css  # accepted for Renderable protocol, no effect on images
+        raw = self._load_data()
+        mime = _detect_mime_type(raw)
+        if mime is None:
+            msg = "Unsupported image format (allowed: PNG, JPEG, GIF, WebP, SVG)"
+            raise RenderError(msg)
+        if mime not in ALLOWED_MIME_TYPES:
+            msg = f"Image type {mime} is not allowed"
+            raise RenderError(msg)
+        if mime == "image/svg+xml":
+            _validate_svg(raw)
+
+        b64 = base64.b64encode(raw).decode("ascii")
+        escaped_alt = html.escape(self.alt)
+
+        attrs = [f'src="data:{mime};base64,{b64}"', f'alt="{escaped_alt}"']
+        if self.width is not None:
+            attrs.append(f'width="{self.width}"')
+        if self.height is not None:
+            attrs.append(f'height="{self.height}"')
+
+        return f"<img {' '.join(attrs)}>"
+
+
+__all__ = [
+    "ALLOWED_MIME_TYPES",
+    "IMAGE_MAX_BYTES",
+    "MonitorImage",
+]

kstlib/monitoring/kv.py

@@ -0,0 +1,79 @@
+"""MonitorKV render type for key-value pair display.
+
+A ``MonitorKV`` renders as an HTML ``<dl>`` definition list with a
+two-column grid layout, suitable for status summaries and stat panels.
+"""
+
+from __future__ import annotations
+
+import html
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from kstlib.monitoring.cell import StatusCell
+
+if TYPE_CHECKING:
+    from kstlib.monitoring.types import CellValue
+
+
+@dataclass(frozen=True, slots=True)
+class MonitorKV:
+    """A key-value grid rendered as an HTML ``<dl>``.
+
+    Values can be plain scalars or ``StatusCell`` objects for colored badges.
+
+    Attributes:
+        items: Ordered mapping of keys to values.
+        title: Optional heading rendered above the list.
+
+    Examples:
+        >>> from kstlib.monitoring.kv import MonitorKV
+        >>> kv = MonitorKV({"Host": "srv-01", "Port": 8080})
+        >>> "<dl" in kv.render()
+        True
+    """
+
+    items: dict[str, CellValue | StatusCell]
+    title: str = ""
+
+    def render(self, *, inline_css: bool = False) -> str:
+        """Render the key-value pairs as an HTML ``<dl>``.
+
+        Args:
+            inline_css: If True, use inline styles instead of CSS classes.
+
+        Returns:
+            HTML ``<dl>`` string, optionally preceded by an ``<h3>`` title.
+        """
+        parts: list[str] = []
+
+        if self.title:
+            escaped_title = html.escape(self.title)
+            parts.append(f"<h3>{escaped_title}</h3>")
+
+        if inline_css:
+            style = "display:grid;grid-template-columns:auto 1fr;gap:4px 12px"
+            parts.append(f'<dl style="{style}">')
+        else:
+            parts.append('<dl class="monitor-kv">')
+
+        for key, value in self.items.items():
+            escaped_key = html.escape(str(key))
+            if inline_css:
+                parts.append(f'<dt style="font-weight:bold">{escaped_key}</dt>')
+            else:
+                parts.append(f"<dt>{escaped_key}</dt>")
+
+            if isinstance(value, StatusCell):
+                rendered_value = value.render(inline_css=inline_css)
+            else:
+                rendered_value = html.escape(str(value))
+            parts.append(f"<dd>{rendered_value}</dd>")
+
+        parts.append("</dl>")
+        return "".join(parts)
+
+
+__all__ = [
+    "MonitorKV",
+]

kstlib/monitoring/list.py

@@ -0,0 +1,69 @@
+"""MonitorList render type for ordered and unordered lists.
+
+A ``MonitorList`` renders as an HTML ``<ul>`` or ``<ol>`` element,
+suitable for event logs, alert lists, and step-by-step status reports.
+"""
+
+from __future__ import annotations
+
+import html
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from kstlib.monitoring.cell import StatusCell
+
+if TYPE_CHECKING:
+    from kstlib.monitoring.types import CellValue
+
+
+@dataclass(frozen=True, slots=True)
+class MonitorList:
+    """A list rendered as an HTML ``<ul>`` or ``<ol>``.
+
+    Items can be plain scalars or ``StatusCell`` objects for colored badges.
+
+    Attributes:
+        items: Sequence of list items.
+        ordered: If True, render as ``<ol>``; otherwise ``<ul>``.
+        title: Optional heading rendered above the list.
+
+    Examples:
+        >>> from kstlib.monitoring.list import MonitorList
+        >>> ml = MonitorList(["Event A", "Event B"])
+        >>> "<ul>" in ml.render()
+        True
+    """
+
+    items: list[CellValue | StatusCell]
+    ordered: bool = False
+    title: str = ""
+
+    def render(self, *, inline_css: bool = False) -> str:
+        """Render the list as an HTML ``<ul>`` or ``<ol>``.
+
+        Args:
+            inline_css: If True, use inline styles instead of CSS classes.
+
+        Returns:
+            HTML list string, optionally preceded by an ``<h3>`` title.
+        """
+        parts: list[str] = []
+
+        if self.title:
+            escaped_title = html.escape(self.title)
+            parts.append(f"<h3>{escaped_title}</h3>")
+
+        tag = "ol" if self.ordered else "ul"
+        parts.append(f"<{tag}>")
+
+        for item in self.items:
+            rendered = item.render(inline_css=inline_css) if isinstance(item, StatusCell) else html.escape(str(item))
+            parts.append(f"<li>{rendered}</li>")
+
+        parts.append(f"</{tag}>")
+        return "".join(parts)
+
+
+__all__ = [
+    "MonitorList",
+]

kstlib/monitoring/metric.py

@@ -0,0 +1,88 @@
+"""MonitorMetric render type for hero number display.
+
+A ``MonitorMetric`` renders as a ``<div>`` with a large value and an
+optional label, suitable for KPI dashboards (P&L, uptime, etc.).
+"""
+
+from __future__ import annotations
+
+import html
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from kstlib.monitoring._styles import (
+    METRIC_FONT_SIZE,
+    METRIC_LABEL_COLOR,
+    STATUS_COLORS,
+)
+from kstlib.monitoring.types import StatusLevel
+
+if TYPE_CHECKING:
+    from kstlib.monitoring.types import CellValue
+
+
+@dataclass(frozen=True, slots=True)
+class MonitorMetric:
+    """A hero-number metric rendered as an HTML ``<div>``.
+
+    Attributes:
+        value: The metric value to display prominently.
+        label: Optional descriptive label shown below the value.
+        level: Severity level controlling the value color.
+        unit: Optional unit suffix appended to the value (e.g. "%", "ms").
+
+    Examples:
+        >>> from kstlib.monitoring.metric import MonitorMetric
+        >>> from kstlib.monitoring.types import StatusLevel
+        >>> m = MonitorMetric(99.9, label="Uptime", level=StatusLevel.OK, unit="%")
+        >>> "99.9" in m.render()
+        True
+    """
+
+    value: CellValue
+    label: str = ""
+    level: StatusLevel = StatusLevel.OK
+    unit: str = ""
+
+    def render(self, *, inline_css: bool = False) -> str:
+        """Render the metric as an HTML ``<div>``.
+
+        Args:
+            inline_css: If True, use inline styles instead of CSS classes.
+
+        Returns:
+            HTML ``<div>`` string.
+        """
+        escaped_val = html.escape(str(self.value))
+        escaped_unit = html.escape(self.unit)
+        display = f"{escaped_val}{escaped_unit}" if self.unit else escaped_val
+
+        if inline_css:
+            color = STATUS_COLORS[self.level]
+            wrapper_style = "text-align:center;padding:12px"
+            value_style = f"font-size:{METRIC_FONT_SIZE};font-weight:bold;color:{color}"
+            parts = [
+                f'<div style="{wrapper_style}">',
+                f'<div style="{value_style}">{display}</div>',
+            ]
+            if self.label:
+                label_style = f"color:{METRIC_LABEL_COLOR};font-size:0.9em"
+                escaped_label = html.escape(self.label)
+                parts.append(f'<div style="{label_style}">{escaped_label}</div>')
+            parts.append("</div>")
+            return "".join(parts)
+
+        parts = [
+            '<div class="monitor-metric">',
+            f'<div class="metric-value">{display}</div>',
+        ]
+        if self.label:
+            escaped_label = html.escape(self.label)
+            parts.append(f'<div class="metric-label">{escaped_label}</div>')
+        parts.append("</div>")
+        return "".join(parts)
+
+
+__all__ = [
+    "MonitorMetric",
+]