kstlib 2.3.0__tar.gz → 2.4.0__tar.gz

{kstlib-2.3.0/src/kstlib.egg-info → kstlib-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kstlib
-Version: 2.3.0
+Version: 2.4.0
 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>

{kstlib-2.3.0 → kstlib-2.4.0}/pyproject.toml

@@ -368,7 +368,10 @@ ignore = [
 "src/kstlib/logging/__init__.py" = ["S110"]
 "src/kstlib/logging/manager.py" = ["S110"]
 # Mail builder - snapshot/notify path legitimately reassigns same-class private state
-"src/kstlib/mail/builder.py" = ["SLF001"]
+# PLR0913: Many kwargs - notify decorator API exposes mode/collector/include_* options (parametrised decorator pattern, mirrors metrics/decorators.py)
+"src/kstlib/mail/builder.py" = ["SLF001", "PLR0913"]
+# Shared Jinja2 helper - autoescape default is intentionally False: kstlib mail templates are author-controlled (dev), not user input. Callers opt in to autoescape=True for HTML user-facing content.
+"src/kstlib/_shared/jinja.py" = ["S701"]
 # Monitoring image - RenderError chain already raised via "from err"; no additional ignores needed here
 # Monitoring renderer - Markup values are escaped before wrapping; jinja2 Environment defaults to autoescape=True
 "src/kstlib/monitoring/renderer.py" = ["S701", "S704"]

kstlib-2.4.0/src/kstlib/_shared/__init__.py

@@ -0,0 +1,6 @@
+"""Shared cross-module helpers (private to kstlib internals).
+
+Modules under ``kstlib._shared`` are imported via their full path
+(e.g. ``from kstlib._shared.jinja import render_jinja``) rather than
+re-exported here. They are not part of the public ``kstlib`` API.
+"""

kstlib-2.4.0/src/kstlib/_shared/jinja.py

@@ -0,0 +1,91 @@
+"""Shared Jinja2 rendering helpers for kstlib internal modules.
+
+Provides a thin wrapper around :class:`jinja2.Environment` with kstlib's
+default policy:
+
+- :class:`jinja2.ChainableUndefined`: missing variables resolve to empty
+  string (and dotted access on them keeps returning empty), preserving
+  graceful behavior for templates with optional fields.
+- ``keep_trailing_newline=True``: file templates retain their trailing
+  newline if any.
+- ``autoescape=False`` by default: kstlib mail templates are authored by
+  the application developer, not by end users, so the caller controls
+  escaping. Pass ``autoescape=True`` for HTML/XML user-facing content.
+
+These helpers live under ``kstlib._shared`` because they are reused by
+several internal subpackages (``mail``, future migrations of
+``monitoring``). Import via the full path:
+
+    from kstlib._shared.jinja import render_jinja, render_jinja_file
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import jinja2
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+    from pathlib import Path
+
+
+def render_jinja(
+    source: str,
+    context: Mapping[str, Any],
+    *,
+    autoescape: bool = False,
+) -> str:
+    """Render a Jinja2 template string with the provided context.
+
+    Args:
+        source: Jinja2 template source as a string.
+        context: Mapping of variables exposed to the template.
+        autoescape: When True, autoescape HTML/XML special characters.
+            Default False; kstlib mail templates are author-controlled.
+
+    Returns:
+        The rendered template as a string.
+
+    Examples:
+        >>> from kstlib._shared.jinja import render_jinja
+        >>> render_jinja("Hello {{ name }}", {"name": "Ada"})
+        'Hello Ada'
+        >>> render_jinja("{{ missing }}", {})
+        ''
+
+    """
+    env = jinja2.Environment(
+        autoescape=autoescape,
+        undefined=jinja2.ChainableUndefined,
+        keep_trailing_newline=True,
+    )
+    return env.from_string(source).render(**dict(context))
+
+
+def render_jinja_file(
+    path: Path,
+    context: Mapping[str, Any],
+    *,
+    autoescape: bool = False,
+    encoding: str = "utf-8",
+) -> str:
+    """Render a Jinja2 template file with the provided context.
+
+    Reads the file at ``path`` with the requested encoding and renders
+    it via :func:`render_jinja`.
+
+    Args:
+        path: Path to the Jinja2 template file.
+        context: Mapping of variables exposed to the template.
+        autoescape: When True, autoescape HTML/XML special characters.
+        encoding: Text encoding used to read the template file.
+
+    Returns:
+        The rendered template as a string.
+
+    """
+    return render_jinja(path.read_text(encoding=encoding), context, autoescape=autoescape)
+
+
+__all__ = ["render_jinja", "render_jinja_file"]

{kstlib-2.3.0 → kstlib-2.4.0}/src/kstlib/config/loader.py

@@ -318,6 +318,76 @@ def _load_any_config_file(
     return data
 
 
+def _normalize_includes(raw: Any, source_path: pathlib.Path) -> list[str]:
+    """Normalize the raw ``include`` YAML value to a clean list of paths.
+
+    Handles the common footgun where an author leaves ``include:`` with an
+    empty body (or comments out every entry) and gets a cryptic
+    ``TypeError: 'NoneType' object is not iterable`` at iteration time.
+    Normalization rules:
+
+    1. Missing key, ``None``, ``[]``, empty string, or whitespace-only
+       string produces an empty list silently. Commenting out a key is a
+       legitimate editing pattern, not an error worth logging.
+    2. A non-empty string is wrapped as a single-element list after
+       ``strip()``.
+    3. A list whose individual items are ``None``, empty, or whitespace-only
+       has those entries dropped with a single ``WARNING`` log message
+       naming the source file, the drop count, and the original indices.
+    4. Any other top-level type (``int``, ``dict``, ...) or any non-string
+       list item raises :exc:`ConfigFormatError`, consistent with the rest
+       of this loader.
+
+    Args:
+        raw: Raw value of the ``include`` key popped from the YAML mapping.
+        source_path: Path of the YAML file that declared the include, used
+            in log and error messages for actionable feedback.
+
+    Returns:
+        Cleaned list of include path strings. Never ``None`` and never
+        containing ``None`` or empty entries.
+
+    Raises:
+        ConfigFormatError: If ``raw`` is not ``None``, ``str``, or ``list``,
+            or if any list element is not a ``str``.
+
+    """
+    if raw is None:
+        return []
+    if isinstance(raw, str):
+        stripped = raw.strip()
+        return [stripped] if stripped else []
+    if not isinstance(raw, list):
+        raise ConfigFormatError(f"include must be string or list, got {type(raw).__name__} (file: {source_path})")
+
+    cleaned: list[str] = []
+    dropped: list[int] = []
+    for idx, item in enumerate(raw):
+        if item is None:
+            dropped.append(idx)
+            continue
+        if not isinstance(item, str):
+            raise ConfigFormatError(f"include[{idx}] must be string, got {type(item).__name__} (file: {source_path})")
+        stripped = item.strip()
+        if not stripped:
+            dropped.append(idx)
+            continue
+        cleaned.append(stripped)
+
+    if dropped:
+        # Lazy import: keep loader import graph shallow (see kstlib.limits
+        # circular import fix).
+        import logging
+
+        logging.getLogger(__name__).warning(
+            "include in %s: dropped %d empty entries at indices %s",
+            source_path,
+            len(dropped),
+            dropped,
+        )
+    return cleaned
+
+
 def _load_with_includes(
     path: pathlib.Path,
     loaded_paths: set[pathlib.Path] | None = None,
@@ -365,9 +435,7 @@ def _load_with_includes(
     loaded_paths.add(path)
 
     data = _load_any_config_file(path, encoding, sops_decrypt=sops_decrypt)
-    includes = data.pop("include", [])
-    if isinstance(includes, str):
-        includes = [includes]
+    includes = _normalize_includes(data.pop("include", []), path)
 
     # Get real extension (handles .sops.yml -> .yml)
     parent_ext = get_real_extension(path) if is_sops_file(path) else path.suffix.lower()

{kstlib-2.3.0 → kstlib-2.4.0}/src/kstlib/limits.py

@@ -16,52 +16,26 @@ Example:
 
 from __future__ import annotations
 
-from collections.abc import Mapping
-from dataclasses import dataclass
-from typing import Any
-
-from kstlib.utils.formatting import format_bytes, parse_size_string
-
-__all__ = [
-    "HARD_MAX_CONFIG_FILE_SIZE",
-    "HARD_MAX_DATETIME_FORMAT_LENGTH",
-    "HARD_MAX_DISPLAY_VALUE_LENGTH",
-    "HARD_MAX_ENDPOINT_REF_LENGTH",
-    "HARD_MAX_EPOCH_TIMESTAMP",
-    "HARD_MAX_PIPELINE_STEPS",
-    "HARD_MAX_PIPELINE_TIMEOUT",
-    "HARD_MAX_RAPI_UPLOAD_SIZE",
-    "HARD_MAX_STEP_ARGS",
-    "HARD_MAX_TIMEZONE_LENGTH",
-    "HARD_MIN_EPOCH_TIMESTAMP",
-    "HARD_MIN_PIPELINE_TIMEOUT",
-    "AlertsLimits",
-    "CacheLimits",
-    "DatabaseLimits",
-    "MailLimits",
-    "PipelineLimits",
-    "RapiLimits",
-    "RapiRenderConfig",
-    "ResilienceLimits",
-    "SopsLimits",
-    "WebSocketLimits",
-    "clamp_with_limits",
-    "get_alerts_limits",
-    "get_cache_limits",
-    "get_db_limits",
-    "get_mail_limits",
-    "get_pipeline_limits",
-    "get_rapi_limits",
-    "get_rapi_render_config",
-    "get_resilience_limits",
-    "get_sops_limits",
-    "get_websocket_limits",
-]
-
 # =============================================================================
-# Hard limits (deep defense - cannot be exceeded via config)
+# Pre-import constants (hard limits + defaults)
+#
+# Defined BEFORE any cross-module import to break a latent circular import.
+# During `kstlib.limits` initialisation, importing `kstlib.utils.formatting`
+# transitively triggers `kstlib.config.__init__`, which re-enters
+# `kstlib.limits` from two points:
+#   - `kstlib.config.loader` -> reads HARD_MAX_CONFIG_FILE_SIZE
+#   - `kstlib.config.sops`   -> reads DEFAULT_MAX_SOPS_CACHE_ENTRIES and
+#                               HARD_MAX_SOPS_CACHE_ENTRIES
+# Both the HARD_* block below and the DEFAULT_* block that follows must
+# therefore be defined before the cross-module import. If these constants
+# sat at their usual position (after imports), Python would raise
+# ImportError on the cycle re-entry into a still-initialising kstlib.limits.
+#
+# See: fix-circular-import-mail request (2026-04-24).
 # =============================================================================
 
+# Hard limits (deep defense - cannot be exceeded via config)
+
 #: Absolute maximum attachment size (25 MiB) - protects against memory exhaustion.
 HARD_MAX_ATTACHMENT_SIZE = 25 * 1024 * 1024
 
@@ -240,9 +214,7 @@ HARD_MIN_EPOCH_TIMESTAMP = 0
 #: Maximum valid epoch timestamp (year 2100) - protects against overflow.
 HARD_MAX_EPOCH_TIMESTAMP = 4102444800
 
-# =============================================================================
 # Default limits (used when config is not available)
-# =============================================================================
 
 DEFAULT_MAX_ATTACHMENT_SIZE = 25 * 1024 * 1024  # 25 MiB
 DEFAULT_MAX_ATTACHMENTS = 20
@@ -291,6 +263,52 @@ DEFAULT_WS_DISCONNECT_ALERT_INTERVAL = 300.0  # seconds between throttled alerts
 DEFAULT_PIPELINE_TIMEOUT = 300.0  # seconds (5 minutes)
 DEFAULT_PIPELINE_ON_ERROR = "fail_fast"
 
+# =============================================================================
+# Cross-module imports (intentionally after pre-import constants, see note above)
+# =============================================================================
+
+from collections.abc import Mapping  # noqa: E402
+from dataclasses import dataclass  # noqa: E402
+from typing import Any  # noqa: E402
+
+from kstlib.utils.formatting import format_bytes, parse_size_string  # noqa: E402
+
+__all__ = [
+    "HARD_MAX_CONFIG_FILE_SIZE",
+    "HARD_MAX_DATETIME_FORMAT_LENGTH",
+    "HARD_MAX_DISPLAY_VALUE_LENGTH",
+    "HARD_MAX_ENDPOINT_REF_LENGTH",
+    "HARD_MAX_EPOCH_TIMESTAMP",
+    "HARD_MAX_PIPELINE_STEPS",
+    "HARD_MAX_PIPELINE_TIMEOUT",
+    "HARD_MAX_RAPI_UPLOAD_SIZE",
+    "HARD_MAX_STEP_ARGS",
+    "HARD_MAX_TIMEZONE_LENGTH",
+    "HARD_MIN_EPOCH_TIMESTAMP",
+    "HARD_MIN_PIPELINE_TIMEOUT",
+    "AlertsLimits",
+    "CacheLimits",
+    "DatabaseLimits",
+    "MailLimits",
+    "PipelineLimits",
+    "RapiLimits",
+    "RapiRenderConfig",
+    "ResilienceLimits",
+    "SopsLimits",
+    "WebSocketLimits",
+    "clamp_with_limits",
+    "get_alerts_limits",
+    "get_cache_limits",
+    "get_db_limits",
+    "get_mail_limits",
+    "get_pipeline_limits",
+    "get_rapi_limits",
+    "get_rapi_render_config",
+    "get_resilience_limits",
+    "get_sops_limits",
+    "get_websocket_limits",
+]
+
 
 @dataclass(frozen=True, slots=True)
 class MailLimits:

{kstlib-2.3.0 → kstlib-2.4.0}/src/kstlib/mail/__init__.py

@@ -25,6 +25,7 @@ Examples:
 """
 
 from kstlib.mail.builder import MailBuilder, NotifyResult
+from kstlib.mail.collector import NotifyCollector
 from kstlib.mail.exceptions import MailConfigurationError, MailError, MailTransportError, MailValidationError
 from kstlib.mail.filesystem import MailFilesystemGuards
 from kstlib.mail.transport import AsyncMailTransport, AsyncTransportWrapper, MailTransport
@@ -39,5 +40,6 @@ __all__ = [
     "MailTransport",
     "MailTransportError",
     "MailValidationError",
+    "NotifyCollector",
     "NotifyResult",
 ]