kstlib 2.3.0__tar.gz → 2.3.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kstlib
-Version: 2.3.0
+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.3.0 → 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()

{kstlib-2.3.0 → 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:

{kstlib-2.3.0 → kstlib-2.3.1}/src/kstlib/meta.py

@@ -39,7 +39,7 @@ __logo__ = (
 )
 
 __app_name__ = "kstlib"
-__version__ = "2.3.0"
+__version__ = "2.3.1"
 __description__ = (
     "Config-driven helpers for Python projects (dynamic config, secure secrets, preset logging, and more…)"
 )

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

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