kstlib 2.2.1__tar.gz → 2.3.1__tar.gz

{kstlib-2.2.1/src/kstlib.egg-info → kstlib-2.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kstlib
-Version: 2.2.1
+Version: 2.3.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>

{kstlib-2.2.1 → kstlib-2.3.1}/src/kstlib/__init__.py

@@ -69,6 +69,7 @@ __all__ = [
     "ops",
     "pipeline",
     "rapi",
+    "reload_config",
     "require_config",
     "resilience",
     "secrets",
@@ -117,6 +118,7 @@ _LAZY_IMPORTS: dict[str, tuple[str, str]] = {
     "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"),
+    "reload_config": ("kstlib.config.loader", "reload_config"),
     "require_config": ("kstlib.config.loader", "require_config"),
     # Logging
     "LogManager": ("kstlib.logging", "LogManager"),
@@ -250,6 +252,9 @@ if TYPE_CHECKING:
     from kstlib.config.loader import (
         load_from_file as load_from_file,
     )
+    from kstlib.config.loader import (
+        reload_config as reload_config,
+    )
     from kstlib.config.loader import (
         require_config as require_config,
     )

{kstlib-2.2.1 → kstlib-2.3.1}/src/kstlib/config/__init__.py

@@ -34,6 +34,7 @@ from kstlib.config.loader import (
     load_config,
     load_from_env,
     load_from_file,
+    reload_config,
     require_config,
 )
 from kstlib.config.sops import (
@@ -71,6 +72,7 @@ __all__ = [
     "load_config",
     "load_from_env",
     "load_from_file",
+    "reload_config",
     "require_config",
     "reset_decryptor",
 ]

{kstlib-2.2.1 → kstlib-2.3.1}/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()
@@ -1064,6 +1132,47 @@ def clear_config() -> None:
     _default_loader.cache = None
 
 
+def reload_config(filename: str = CONFIG_FILENAME) -> Box:
+    """Force-reload the singleton configuration from disk.
+
+    Equivalent to ``clear_config()`` followed by ``get_config()``, but explicit
+    and discoverable in a single import. Designed for interactive sessions
+    (Jupyter, REPL) where the underlying YAML files have been edited and the
+    cached config needs to be refreshed without restarting the kernel.
+
+    Args:
+        filename: Config filename to search for. Defaults to
+            ``kstlib.conf.yml``.
+
+    Returns:
+        Freshly loaded ``Box`` configuration object. The singleton cache is
+        updated in-place, so subsequent ``get_config()`` calls return the same
+        fresh object.
+
+    Raises:
+        ConfigFileNotFoundError: If no configuration file is found in any
+            search location.
+
+    Note:
+        When to use which:
+
+        - ``reload_config()``: explicit one-shot refresh (Jupyter/REPL).
+        - ``get_config(force_reload=True)``: same effect, but the intent is
+          hidden in a kwarg.
+        - ``clear_config()``: only flushes the cache; the next
+          ``get_config()`` call triggers the actual reload. Useful in tests
+          that want to isolate the cache boundary.
+
+    Examples:
+        >>> from kstlib.config import reload_config
+        >>> cfg = reload_config()  # doctest: +SKIP
+        >>> cfg.mail.default  # doctest: +SKIP
+        'corporate'
+
+    """
+    return get_config(filename=filename, force_reload=True)
+
+
 __all__ = [
     "AutoDiscoveryConfig",
     "ConfigLoader",
@@ -1072,5 +1181,6 @@ __all__ = [
     "load_config",
     "load_from_env",
     "load_from_file",
+    "reload_config",
     "require_config",
 ]

{kstlib-2.2.1 → kstlib-2.3.1}/src/kstlib/kstlib.conf.yml

@@ -358,6 +358,21 @@ mail:
   # Leave null to force callers to pass transport= or preset= explicitly.
   default: null
 
+  # SSL/TLS configuration for mail transports.
+  #
+  # Values here override the root ``ssl:`` section (bottom of this file)
+  # for mail only, and are themselves overridden by ``ssl_verify`` and
+  # ``ssl_ca_bundle`` keys set inside an individual preset. Each key
+  # cascades independently: you can set ``verify: false`` here and still
+  # provide ``ssl_ca_bundle`` at the preset level.
+  #
+  # Security: setting ``verify: false`` at any level emits a WARNING log
+  # at transport build time. Prefer ``ca_bundle: /path/to/private-ca.pem``
+  # for internal PKI rather than disabling verification outright.
+  ssl:
+    verify: true
+    ca_bundle: null
+
   # Named transport presets. Each preset declares a "transport" field
   # (smtp or resend) and backend-specific parameters. Define your own
   # presets here and reference them via MailBuilder(preset="name").
@@ -368,11 +383,18 @@ mail:
   #   transport: smtp
   #   host: smtp-secure.corp.local
   #   port: 25
-  #   login: svc_user
+  #   login: svc_mail
   #   password: "secret"
   #   starttls: false
   #   ssl: false
   #   timeout: 30
+  #   # Optional SSL overrides for this preset (highest priority in the cascade):
+  #   ssl_verify: false
+  #   ssl_ca_bundle: /etc/ssl/certs/corp-ca.pem
+  #   # Optional envelope defaults (sender / reply_to only, never to/cc/bcc):
+  #   defaults:
+  #     sender: "Service Notifications <notify@corp.local>"
+  #     reply_to: "Service Notifications <notify@corp.local>"
   #
   # transactional:
   #   transport: resend

{kstlib-2.2.1 → kstlib-2.3.1}/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: