kstlib 2.6.0__tar.gz → 2.7.1__tar.gz

{kstlib-2.6.0/src/kstlib.egg-info → kstlib-2.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kstlib
-Version: 2.6.0
+Version: 2.7.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>
@@ -46,7 +46,7 @@ Requires-Dist: authlib<2,>=1.6.11
 Requires-Dist: pendulum<4,>=3.0
 Requires-Dist: cryptography>=46.0.7
 Requires-Dist: requests>=2.33.0
-Requires-Dist: urllib3>=2.6.3
+Requires-Dist: urllib3>=2.7.0
 Provides-Extra: dev
 Requires-Dist: pytest<10,>=9.0.3; extra == "dev"
 Requires-Dist: pytest-cov<8,>=7.0; extra == "dev"

{kstlib-2.6.0 → kstlib-2.7.1}/pyproject.toml

@@ -64,7 +64,7 @@ dependencies = [
     # --- Security: transitive dep lower bounds (CVE) ---
     "cryptography>=46.0.7",  # CVE-2026-26007 + CVE-2026-34073 + CVE-2026-39892
     "requests>=2.33.0",      # CVE-2024-47081 + CVE-2026-25645 (via httpx)
-    "urllib3>=2.6.3",         # CVE-2025-50182/50181 + CVE-2025-66418/66471 + CVE-2026-21441 (via requests)
+    "urllib3>=2.7.0",         # CVE-2025-50182/50181 + CVE-2025-66418/66471 + CVE-2026-21441 + CVE-2026-44431 + CVE-2026-44432 (via requests)
 ]
 classifiers = [
     "Development Status :: 5 - Production/Stable",

{kstlib-2.6.0 → kstlib-2.7.1}/src/kstlib/__init__.py

@@ -39,6 +39,11 @@ from __future__ import annotations
 import importlib
 from typing import TYPE_CHECKING, Any
 
+# Eager-loaded version string (PEP 396 / standard ergonomy).
+# Imported eagerly so `kstlib.__version__` works without triggering the
+# lazy-loader. The cost is negligible (one trivial module load).
+from kstlib.meta import __version__
+
 # Public API exports (sorted alphabetically)
 __all__ = [
     "ConfigCircularIncludeError",
@@ -52,6 +57,7 @@ __all__ = [
     "MonitoringError",
     "PanelManager",
     "PanelRenderingError",
+    "__version__",
     "alerts",
     "app",
     "auth",

{kstlib-2.6.0 → kstlib-2.7.1}/src/kstlib/auth/callback.py

@@ -327,7 +327,7 @@ class CallbackServer:  # pylint: disable=too-many-instance-attributes
         if self._server is None:
             return
         while not self._stop_flag and self._server:
-            try:
+            try:  # reason: per-iteration tolerance for HTTP request handler loop
                 self._server.handle_request()
             except Exception:  # pylint: disable=broad-exception-caught
                 if not self._stop_flag:

{kstlib-2.6.0 → kstlib-2.7.1}/src/kstlib/auth/check.py

@@ -171,6 +171,7 @@ class TokenChecker:
         expected_issuer: str | None = None,
         expected_audience: str | None = None,
     ) -> None:
+        """Initialize the token checker with an HTTP client and optional expected claims."""
         self._http = http_client
         self._expected_issuer = expected_issuer
         self._expected_audience = expected_audience

{kstlib-2.6.0 → kstlib-2.7.1}/src/kstlib/auth/errors.py

@@ -11,6 +11,7 @@ class AuthError(KstlibError):
     """Base exception for all authentication errors."""
 
     def __init__(self, message: str, *, details: dict[str, Any] | None = None) -> None:
+        """Initialize the auth error with a message and optional structured details."""
         super().__init__(message)
         self.message = message
         self.details = details or {}
@@ -24,6 +25,7 @@ class ProviderNotFoundError(AuthError):
     """Raised when a named provider is not configured."""
 
     def __init__(self, provider_name: str) -> None:
+        """Initialize with the name of the missing provider."""
         super().__init__(f"Provider '{provider_name}' not found in configuration")
         self.provider_name = provider_name
 
@@ -32,6 +34,7 @@ class DiscoveryError(AuthError):
     """Raised when OIDC discovery fails."""
 
     def __init__(self, issuer: str, reason: str) -> None:
+        """Initialize with the failing issuer URL and the reason for the failure."""
         super().__init__(f"Discovery failed for '{issuer}': {reason}")
         self.issuer = issuer
         self.reason = reason
@@ -49,6 +52,7 @@ class TokenRefreshError(TokenError):
     """Raised when token refresh fails."""
 
     def __init__(self, reason: str, *, retryable: bool = False) -> None:
+        """Initialize with the reason for the refresh failure and a retryable flag."""
         super().__init__(f"Token refresh failed: {reason}")
         self.reason = reason
         self.retryable = retryable
@@ -58,6 +62,7 @@ class TokenExchangeError(TokenError):
     """Raised when authorization code exchange fails."""
 
     def __init__(self, reason: str, *, error_code: str | None = None) -> None:
+        """Initialize with the reason for the exchange failure and an optional OAuth error code."""
         super().__init__(f"Token exchange failed: {reason}")
         self.reason = reason
         self.error_code = error_code
@@ -67,6 +72,7 @@ class TokenValidationError(TokenError):
     """Raised when JWT validation fails (signature, claims, expiry)."""
 
     def __init__(self, reason: str, *, claim: str | None = None) -> None:
+        """Initialize with the reason for the validation failure and the offending claim name."""
         super().__init__(f"Token validation failed: {reason}")
         self.reason = reason
         self.claim = claim
@@ -86,6 +92,7 @@ class AuthorizationError(AuthError):
         error_code: str | None = None,
         error_description: str | None = None,
     ) -> None:
+        """Initialize with the reason for the failure plus optional OAuth error code and description."""
         super().__init__(f"Authorization failed: {reason}")
         self.reason = reason
         self.error_code = error_code
@@ -96,6 +103,7 @@ class CallbackServerError(AuthError):
     """Raised when the local callback server fails to start or receive callback."""
 
     def __init__(self, reason: str, *, port: int | None = None) -> None:
+        """Initialize with the reason for the callback server failure and the port that was in use."""
         super().__init__(f"Callback server error: {reason}")
         self.reason = reason
         self.port = port
@@ -105,6 +113,7 @@ class PreflightError(AuthError):
     """Raised when preflight validation fails."""
 
     def __init__(self, step: str, reason: str) -> None:
+        """Initialize with the failing preflight step name and the reason for the failure."""
         super().__init__(f"Preflight failed at '{step}': {reason}")
         self.step = step
         self.reason = reason

{kstlib-2.6.0 → kstlib-2.7.1}/src/kstlib/auth/providers/oauth2.py

@@ -453,7 +453,7 @@ class OAuth2Provider(AbstractAuthProvider):
 
         success = False
         for token_type_hint, token_value in tokens_to_revoke:
-            try:
+            try:  # reason: per-token revocation; partial success allowed (RFC 7009)
                 data: dict[str, Any] = {
                     "token": token_value,
                     "token_type_hint": token_type_hint,

{kstlib-2.6.0 → kstlib-2.7.1}/src/kstlib/cli/commands/ops/common.py

@@ -202,6 +202,7 @@ def _scan_tmux_sockets(name: str) -> tuple[str | None, str | None]:
         Tuple of (backend, socket_name). Both are ``None`` if no match is
         found. When a socket holds the session, ``("tmux", <sock>)`` is
         returned.
+
     """
     for sock in discover_tmux_sockets():
         try:

{kstlib-2.6.0 → kstlib-2.7.1}/src/kstlib/cli/commands/ops/list_sessions.py

@@ -163,7 +163,7 @@ def _collect_sessions(backend: str | None) -> list[SessionStatus]:
 
         # Discover sessions on custom tmux sockets
         for socket_name in discover_tmux_sockets():
-            try:
+            try:  # reason: per-socket discovery; missing tmux socket is non-fatal
                 tmux = TmuxRunner(socket_name=socket_name)
                 sessions.extend(tmux.list_sessions())
             except BackendNotFoundError:

{kstlib-2.6.0 → kstlib-2.7.1}/src/kstlib/db/pool.py

@@ -281,7 +281,7 @@ class ConnectionPool:
         async with self._lock:
             # Close all connections
             for conn in self._connections:
-                try:
+                try:  # reason: per-connection best-effort close on pool teardown
                     await conn.execute("PRAGMA optimize")
                     await conn.execute("PRAGMA wal_checkpoint(TRUNCATE)")
                     await conn.close()
@@ -292,7 +292,7 @@ class ConnectionPool:
 
             # Empty the queue
             while not self._pool.empty():
-                try:
+                try:  # reason: race-safe queue drain (QueueEmpty IS the loop terminator)
                     self._pool.get_nowait()
                 except asyncio.QueueEmpty:
                     break

{kstlib-2.6.0 → kstlib-2.7.1}/src/kstlib/kstlib.conf.yml

@@ -424,6 +424,39 @@ mail:
   # Leave null to force callers to pass transport= or preset= explicitly.
   default: null
 
+  # Anti-spam throttle (kill switch). Enforced before the transport on
+  # every MailBuilder.send(), including indirect calls via @mail.notify.
+  #
+  # Cascade (highest priority first):
+  #   1. mail.presets.<name>.throttle.<key>  (preset-level override)
+  #   2. mail.throttle.<key>                 (this section, mail-wide default)
+  #   3. Code defaults                       (rate=20, per=60.0, on_exceed=raise)
+  #
+  # Each key cascades independently: a preset can override only ``rate``
+  # while keeping the mail-wide ``per`` and ``on_exceed``.
+  #
+  # Modes:
+  #   - raise (default): emits WARNING [SECURITY] then raises
+  #     MailThrottledError. The caller decides how to back off.
+  #   - warn: emits WARNING [SECURITY] then drops the mail silently
+  #     (returns the built message without sending).
+  #   - drop (silent) is INTENTIONALLY REJECTED at init: a security
+  #     event must never be silent (kstlib logging convention).
+  #
+  # Singleton: a single MailThrottle is shared across all builders that
+  # use the same preset, including snapshots taken by the @notify
+  # decorator. This prevents bypass via creating many builder instances.
+  #
+  # Hard limits enforced in code (see kstlib.limits):
+  #   - rate: 1 to 1000 mails per period
+  #   - per: 1.0 to 86400.0 seconds (1 day)
+  #   - on_exceed: "raise" or "warn"
+  throttle:
+    enabled: true
+    rate: 20
+    per: 60.0
+    on_exceed: raise
+
   # SSL/TLS configuration for mail transports.
   #
   # Values here override the root ``ssl:`` section (bottom of this file)
@@ -461,6 +494,11 @@ mail:
   #   defaults:
   #     sender: "Service Notifications <notify@corp.local>"
   #     reply_to: "Service Notifications <notify@corp.local>"
+  #   # Optional throttle override (highest priority, see mail.throttle above):
+  #   throttle:
+  #     rate: 5            # corporate is more restrictive than mail-wide default
+  #     per: 60.0
+  #     on_exceed: warn    # operational critical, prefer drop+log over raise
   #
   # transactional:
   #   transport: resend

{kstlib-2.6.0 → kstlib-2.7.1}/src/kstlib/limits.py

@@ -16,6 +16,8 @@ Example:
 
 from __future__ import annotations
 
+from typing import Literal as _Literal
+
 # =============================================================================
 # Pre-import constants (hard limits + defaults)
 #
@@ -126,6 +128,11 @@ HARD_MAX_THROTTLE_RATE = 1000
 HARD_MIN_THROTTLE_PER = 1.0
 HARD_MAX_THROTTLE_PER = 86400.0  # 1 day
 
+#: Mail throttle registry size cap. Beyond this number of distinct preset
+#: names, get_or_create_throttle refuses new entries to bound memory under
+#: multi-tenant misuse (e.g. dynamic UUID-suffixed preset names).
+HARD_MAX_THROTTLE_REGISTRY_SIZE = 100
+
 #: Alert channel timeout bounds (seconds) - protects against too short or hanging requests.
 HARD_MIN_CHANNEL_TIMEOUT = 1.0
 HARD_MAX_CHANNEL_TIMEOUT = 120.0
@@ -246,6 +253,13 @@ DEFAULT_THROTTLE_BURST = 5  # initial capacity
 DEFAULT_CHANNEL_TIMEOUT = 30.0  # seconds
 DEFAULT_CHANNEL_RETRIES = 2
 
+#: Mail throttle defaults (anti-spam kill switch).
+#: Hard limits are shared with alerts (HARD_MIN/MAX_THROTTLE_RATE / _PER).
+#: Mode 'drop' is intentionally not supported (security event must never be silent).
+DEFAULT_MAIL_THROTTLE_RATE = 20  # mails per period
+DEFAULT_MAIL_THROTTLE_PER = 60.0  # seconds
+DEFAULT_MAIL_THROTTLE_ON_EXCEED: _Literal["raise", "warn"] = "raise"
+
 DEFAULT_WS_PING_INTERVAL = 20.0  # seconds
 DEFAULT_WS_PING_TIMEOUT = 10.0  # seconds
 DEFAULT_WS_CONNECTION_TIMEOUT = 30.0  # seconds

{kstlib-2.6.0 → kstlib-2.7.1}/src/kstlib/logging/manager.py

@@ -74,7 +74,8 @@ FORBIDDEN_PATH_COMPONENTS: frozenset[str] = frozenset({"..", "~"})
 ALLOWED_LOG_EXTENSIONS: frozenset[str] = frozenset({".log", ".txt", ".json", ""})
 
 
-# TODO: Add aiofiles for true async file I/O
+# Native async file I/O via aiofiles is a potential future enhancement;
+# current implementation uses thread-pool wrappers (see methods below).
 # try:
 #     import aiofiles
 #     import aiofiles.os
@@ -882,7 +883,8 @@ class LogManager(logging.Logger):
         """Return whether native async logs are available."""
         return HAS_ASYNC
 
-    # Async logging methods (TODO: implement with aiofiles)
+    # Async logging methods (thread-pool wrappers; native aiofiles via
+    # optional dep is a potential future optimization).
 
     async def atrace(self, msg: str, **context: Any) -> None:
         """Async trace wrapper executed via thread pool."""

{kstlib-2.6.0 → kstlib-2.7.1}/src/kstlib/mail/__init__.py

@@ -26,8 +26,15 @@ 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.exceptions import (
+    MailConfigurationError,
+    MailError,
+    MailThrottledError,
+    MailTransportError,
+    MailValidationError,
+)
 from kstlib.mail.filesystem import MailFilesystemGuards
+from kstlib.mail.throttle import MailThrottle
 from kstlib.mail.transport import AsyncMailTransport, AsyncTransportWrapper, MailTransport
 
 __all__ = [
@@ -37,6 +44,8 @@ __all__ = [
     "MailConfigurationError",
     "MailError",
     "MailFilesystemGuards",
+    "MailThrottle",
+    "MailThrottledError",
     "MailTransport",
     "MailTransportError",
     "MailValidationError",

kstlib-2.7.1/src/kstlib/mail/_helpers.py

@@ -0,0 +1,81 @@
+"""Internal helpers for the mail subpackage.
+
+Single source of truth for the ``mail`` configuration section access
+shared by :mod:`kstlib.mail.builder` (cascade transport / SSL / preset
+resolution) and :mod:`kstlib.mail.throttle` (anti-spam kill switch
+init).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from kstlib.mail.exceptions import MailConfigurationError
+
+
+def _load_mail_section(*, silent: bool = False) -> Any:
+    """Read the ``mail`` section from the kstlib configuration.
+
+    Two distinct contracts share this implementation:
+
+    - ``silent=False`` (used by :mod:`kstlib.mail.builder`):
+      preserves the legacy single-exception-type contract. Every loader
+      failure (``ImportError``, ``ConfigNotLoadedError``, ``YAMLError``,
+      ``OSError``, ``RuntimeError``, ...) is wrapped in
+      :class:`~kstlib.mail.MailConfigurationError`. Existing builder
+      callers and tests rely on this wrap.
+
+    - ``silent=True`` (used by :mod:`kstlib.mail.throttle`):
+      narrow catch. Only "config absent / not loaded" errors
+      (``ImportError``, ``ConfigNotLoadedError``,
+      ``MailConfigurationError``) are suppressed and return ``None``.
+      Real corruption (``YAMLError``, ``OSError``, ``RuntimeError``,
+      ...) propagates so the throttle init crashes explicitly rather
+      than silently disabling.
+
+    The asymmetry is intentional: the throttle is an operational
+    kill switch, surfacing corruption is preferable to silently
+    weakening the safety net. Full unification (narrow catch on both
+    paths) would be a breaking change for the builder API and is
+    deferred to a future major release.
+
+    Args:
+        silent: If ``True``, suppress "config not loaded" errors and
+            return ``None``. Real corruption errors always propagate.
+
+    Returns:
+        The mail section as a Box / dict, or ``None`` if the section
+        is missing or (``silent=True``) the config is not loaded.
+
+    Raises:
+        MailConfigurationError: If ``silent=False`` and the config
+            cannot be loaded for any reason. The original exception is
+            chained via ``__cause__``.
+
+    """
+    try:
+        from kstlib.config import get_config
+        from kstlib.config.exceptions import ConfigNotLoadedError
+    except ImportError as exc:  # pragma: no cover - config is always present
+        if silent:
+            return None
+        raise MailConfigurationError("kstlib.config is not available") from exc
+
+    try:
+        cfg: Any = get_config()
+    except (ConfigNotLoadedError, MailConfigurationError) as exc:
+        if silent:
+            return None
+        raise MailConfigurationError(f"Failed to load kstlib configuration: not loaded ({exc})") from exc
+    except Exception as exc:
+        # Real loader corruption (YAMLError, OSError, RuntimeError, ...).
+        # silent path: propagate to surface the bug at builder/throttle init.
+        # non-silent path: wrap into MailConfigurationError to preserve the
+        # legacy single-exception API that existing builder callers rely on.
+        if silent:
+            raise
+        raise MailConfigurationError(f"Failed to load kstlib configuration: {exc}") from exc
+
+    if not hasattr(cfg, "get"):
+        return None
+    return cfg.get("mail")

{kstlib-2.6.0 → kstlib-2.7.1}/src/kstlib/mail/builder.py

@@ -20,8 +20,10 @@ from typing import TYPE_CHECKING, Any, Literal, ParamSpec, TypeVar, overload
 from kstlib._shared.jinja import render_jinja
 from kstlib.limits import MailLimits, get_mail_limits
 from kstlib.logging import get_logger
+from kstlib.mail._helpers import _load_mail_section
 from kstlib.mail.exceptions import MailConfigurationError, MailTransportError, MailValidationError
 from kstlib.mail.filesystem import MailFilesystemGuards
+from kstlib.mail.throttle import MailThrottle, get_or_create_throttle
 from kstlib.ssl import get_ssl_config, validate_ca_bundle_path
 from kstlib.utils import (
     EmailAddress,
@@ -181,6 +183,7 @@ class MailBuilder:
         encoding: str = _DEFAULT_ENCODING,
         filesystem: MailFilesystemGuards | None = None,
         limits: MailLimits | None = None,
+        throttle: bool | dict[str, Any] | None = None,
     ) -> None:
         """Initialise the builder with optional transport, preset, charset, and guardrails.
 
@@ -198,11 +201,20 @@ class MailBuilder:
             filesystem: Filesystem guardrails for attachments, inline
                 resources, and templates.
             limits: Message and attachment limits.
+            throttle: Anti-spam kill switch. ``False`` disables the
+                throttle on this builder. A ``dict`` (e.g.
+                ``{"rate": 100, "per": 3600.0, "on_exceed": "warn"}``)
+                builds a per-instance custom throttle. ``None`` (default)
+                resolves the throttle from configuration via the cascade
+                ``mail.presets.<name>.throttle`` > ``mail.throttle`` >
+                code defaults. See :class:`~kstlib.mail.MailThrottle` for
+                the available knobs.
 
         Raises:
             MailConfigurationError: If ``preset`` is passed but does not
-                resolve to a valid preset in configuration, or if a preset
-                default has a non-string value.
+                resolve to a valid preset in configuration, if a preset
+                default has a non-string value, or if the resolved
+                throttle configuration is invalid.
             MailValidationError: If a preset default holds an unparseable
                 email address.
 
@@ -220,6 +232,7 @@ class MailBuilder:
         self._encoding = encoding
         self._filesystem = filesystem or MailFilesystemGuards.default()
         self._limits = limits or get_mail_limits()
+        self._throttle: MailThrottle | None = get_or_create_throttle(resolved_preset_name, throttle)
         self._sender: EmailAddress | None = None
         self._reply_to: EmailAddress | None = None
         self._to: list[EmailAddress] = []
@@ -380,12 +393,23 @@ class MailBuilder:
     def send(self) -> EmailMessage:
         """Build and send the email using the configured transport.
 
+        If a :class:`~kstlib.mail.MailThrottle` is attached (default,
+        unless disabled via ``throttle=False``), it is consulted before
+        the transport. When the bucket is empty, the throttle either
+        raises :class:`~kstlib.mail.MailThrottledError` (mode ``raise``)
+        or logs a security warning and returns the built message without
+        sending (mode ``warn``).
+
         Returns:
-            The constructed EmailMessage after successful delivery.
+            The constructed :class:`~email.message.EmailMessage`. In
+            ``warn`` mode, the returned message may have been dropped
+            silently (a ``WARNING [SECURITY]`` log is emitted).
 
         Raises:
             MailConfigurationError: If no transport has been configured.
             MailTransportError: If the transport fails to deliver the message.
+            MailThrottledError: If the throttle is in ``raise`` mode and
+                the bucket is empty.
 
         """
         from kstlib.mail.transport import AsyncMailTransport, MailTransport
@@ -400,6 +424,8 @@ class MailBuilder:
             )
         assert isinstance(self._transport, MailTransport)
         message = self.build()
+        if self._throttle is not None and not self._throttle.consume(self._subject):
+            return message
         try:
             self._transport.send(message)
         except MailTransportError:
@@ -415,17 +441,27 @@ class MailBuilder:
     def _snapshot(self) -> MailBuilder:
         """Create an independent copy of this builder for decoration.
 
-        Returns a copy that shares the transport but has independent
-        message state, so decorated functions don't interfere with each other.
+        Returns a copy that shares the transport and throttle but has
+        independent message state, so decorated functions don't interfere
+        with each other. The throttle MUST be shared (not deep-copied)
+        so that ``@mail.notify`` on a hot function cannot bypass the
+        rate limit by getting its own bucket.
         """
-        # Save transport before deepcopy (transports should not be copied)
+        # Save transport and throttle before deepcopy: neither can be
+        # safely deep-copied (transport may hold sockets, throttle holds
+        # a threading.Lock) and both must be shared by reference so the
+        # snapshot enforces the same kill switch as the original builder.
         transport = self._transport
+        throttle = self._throttle
         self._transport = None
+        self._throttle = None
         try:
             snapshot = copy.deepcopy(self)
         finally:
             self._transport = transport
+            self._throttle = throttle
         snapshot._transport = transport
+        snapshot._throttle = throttle
         return snapshot
 
     @overload
@@ -935,32 +971,6 @@ def _detect_mime(path: Path) -> tuple[str, str]:
 _SUPPORTED_TRANSPORTS = ("smtp", "resend")
 
 
-def _load_mail_config() -> Any:
-    """Read ``mail`` section from kstlib configuration.
-
-    Returns:
-        The ``mail`` section as a Box/dict, or ``None`` if unavailable.
-
-    Raises:
-        MailConfigurationError: If the config loader cannot be imported or
-            raises while reading.
-
-    """
-    try:
-        from kstlib.config import get_config
-    except ImportError as exc:  # pragma: no cover - config is always present
-        raise MailConfigurationError("kstlib.config is not available") from exc
-
-    try:
-        cfg: Any = get_config()
-    except Exception as exc:
-        raise MailConfigurationError(f"Failed to load kstlib configuration: {exc}") from exc
-
-    if not hasattr(cfg, "get"):
-        return None
-    return cfg.get("mail")
-
-
 def _resolve_default_transport() -> TransportLike | None:
     """Resolve the transport from ``mail.default`` in configuration.
 
@@ -974,7 +984,7 @@ def _resolve_default_transport() -> TransportLike | None:
 
     """
     try:
-        mail_cfg = _load_mail_config()
+        mail_cfg = _load_mail_section()
     except MailConfigurationError:
         return None
 
@@ -992,10 +1002,10 @@ def _resolve_default_preset_name() -> str | None:
 
     Swallows any config loading error and returns ``None`` so that
     ``MailBuilder()`` stays usable even when the config file is missing.
-    Mirrors the silent-empty contract of :func:`_load_mail_config`.
+    Mirrors the silent-empty contract of :func:`_load_mail_section`.
     """
     try:
-        mail_cfg = _load_mail_config()
+        mail_cfg = _load_mail_section()
     except MailConfigurationError:
         return None
     if mail_cfg is None or not hasattr(mail_cfg, "get"):
@@ -1029,7 +1039,7 @@ def _load_preset_envelope_defaults(preset_name: str) -> dict[str, Any]:
 
     """
     try:
-        mail_cfg = _load_mail_config()
+        mail_cfg = _load_mail_section()
     except MailConfigurationError:
         return {}
     if mail_cfg is None or not hasattr(mail_cfg, "get"):
@@ -1078,7 +1088,7 @@ def _build_transport_from_preset(preset_name: str) -> TransportLike:
             field is missing or unsupported, or required fields are absent.
 
     """
-    mail_cfg = _load_mail_config()
+    mail_cfg = _load_mail_section()
     if mail_cfg is None:
         raise MailConfigurationError(
             f"Preset '{preset_name}' cannot be resolved: 'mail' section missing from configuration"
@@ -1113,7 +1123,7 @@ def _load_mail_ssl_section() -> Any | None:
     config loader cannot be reached.
     """
     try:
-        mail_section = _load_mail_config()
+        mail_section = _load_mail_section()
     except MailConfigurationError:
         return None
     if mail_section is None or not hasattr(mail_section, "get"):

{kstlib-2.6.0 → kstlib-2.7.1}/src/kstlib/mail/exceptions.py

@@ -21,9 +21,23 @@ class MailConfigurationError(MailError):
     """Raised when the mail builder is missing required configuration."""
 
 
+class MailThrottledError(MailError):
+    """Raised when the mail throttle bucket is empty and on_exceed is 'raise'.
+
+    Carries the throttle parameters in the message to help the caller
+    decide on a backoff strategy. The throttle is config-driven via
+    ``mail.throttle.*`` and acts as an anti-spam kill switch.
+
+    See Also:
+        :class:`kstlib.mail.MailThrottle`
+
+    """
+
+
 __all__ = [
     "MailConfigurationError",
     "MailError",
+    "MailThrottledError",
     "MailTransportError",
     "MailValidationError",
 ]