bitranox-template-py-cli 2.3.0__tar.gz → 2.4.0__tar.gz

{bitranox_template_py_cli-2.3.0 → bitranox_template_py_cli-2.4.0}/CHANGELOG.md

@@ -6,6 +6,19 @@ the [Keep a Changelog](https://keepachangelog.com/) format.
 
 ## [Unreleased]
 
+## [2.4.0] 2026-10-08 17:34:36
+
+### Changed
+- **The email commands' SMTP options reach the configuration as a typed `EmailConfigOverrides`
+  model instead of a plain dict.** `EmailConfigOverrides.from_cli_options(...)` takes the Click
+  values (an option that was not given is `None`, an unset `--smtp-host` an empty tuple) and
+  `apply_validated_overrides` merges only the options that were given. Its fields carry
+  EmailConfig's own names, so a field EmailConfig renames is refused instead of slipping through,
+  and `--smtp-password` is a `SecretStr` from the moment it is read; the model is a btx_lib_mail
+  `SecretSafeModel`, so a refused password never appears in a validation error's details.
+  `filter_sentinels` is gone; the command line behaves as before.
+- Requires `pydantic>=2.14.0` (and `virtualenv>=21.14.6` in the dev extra).
+
 ## [2.3.0] 2026-10-08 16:14:12
 
 ### Changed

{bitranox_template_py_cli-2.3.0 → bitranox_template_py_cli-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bitranox_template_py_cli
-Version: 2.3.0
+Version: 2.4.0
 Summary: Template CLI application with configuration management and structured logging
 Project-URL: Homepage, https://github.com/bitranox/bitranox_template_py_cli
 Project-URL: Repository, https://github.com/bitranox/bitranox_template_py_cli.git
@@ -27,7 +27,7 @@ Requires-Dist: lib-cli-exit-tools>=2.4.0
 Requires-Dist: lib-layered-config>=7.0.1
 Requires-Dist: lib-log-rich>=6.4.2
 Requires-Dist: orjson>=3.13.0
-Requires-Dist: pydantic>=2.13.5
+Requires-Dist: pydantic>=2.14.0
 Requires-Dist: python-dotenv>=1.2.4
 Requires-Dist: rich-click>=1.9.9
 Provides-Extra: dev
@@ -49,7 +49,7 @@ Requires-Dist: ruff>=0.16.10; extra == 'dev'
 Requires-Dist: textual>=8.2.8; extra == 'dev'
 Requires-Dist: twine>=7.0.0; extra == 'dev'
 Requires-Dist: urllib3>=2.8.0; extra == 'dev'
-Requires-Dist: virtualenv>=21.14.5; extra == 'dev'
+Requires-Dist: virtualenv>=21.14.6; extra == 'dev'
 Requires-Dist: wheel>=0.48.0; extra == 'dev'
 Description-Content-Type: text/markdown
 

{bitranox_template_py_cli-2.3.0 → bitranox_template_py_cli-2.4.0}/docs/systemdesign/module_reference.md

@@ -40,7 +40,8 @@ moves or removes a module, a CLI option or a public name.
   - `commands/info.py`  -  info, hello, fail commands
   - `commands/config.py`  -  config, config-deploy, config-generate-examples commands
   - `commands/email/`  -  Email commands package:
-    - `_common.py`  -  Shared SMTP override options, config loading and error-to-exit-code mapping
+    - `_common.py`  -  Shared SMTP override options and their typed `EmailConfigOverrides`, config
+      loading and error-to-exit-code mapping
     - `send_email.py`  -  send-email command
     - `send_notification.py`  -  send-notification command
   - `commands/logging.py`  -  logdemo command

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

@@ -1,6 +1,6 @@
 [project]
 name = "bitranox_template_py_cli"
-version = "2.3.0"
+version = "2.4.0"
 description = "Template CLI application with configuration management and structured logging"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -14,7 +14,7 @@ dependencies = [
     "python-dotenv>=1.2.4",
     "lib_layered_config>=7.0.1",
     "btx_lib_mail>=4.0.0",
-    "pydantic>=2.13.5",
+    "pydantic>=2.14.0",
     "orjson>=3.13.0",
 ]
 license = { text = "MIT" }
@@ -77,7 +77,7 @@ dev = [
   "wheel>=0.48.0",               # CVE-2025-24049
   "pynacl>=1.6.2",               # CVE-2025-69277
   "urllib3>=2.8.0",              # CVE-2025-66471, CVE-2025-66418
-  "virtualenv>=21.14.5",         # CVE-2025-22702
+  "virtualenv>=21.14.6",         # CVE-2025-22702
 ]
 
 [project.scripts]

{bitranox_template_py_cli-2.3.0 → bitranox_template_py_cli-2.4.0}/src/bitranox_template_py_cli/__init__conf__.py

@@ -40,7 +40,7 @@ name = "bitranox_template_py_cli"
 #: Human-readable summary shown in CLI help output.
 title = "Template CLI application with configuration management and structured logging"
 #: Current release version pulled from ``pyproject.toml`` by automation.
-version = "2.3.0"
+version = "2.4.0"
 #: Repository homepage presented to users.
 homepage = "https://github.com/bitranox/bitranox_template_py_cli"
 #: Author attribution surfaced in CLI output.

{bitranox_template_py_cli-2.3.0 → bitranox_template_py_cli-2.4.0}/src/bitranox_template_py_cli/adapters/cli/commands/email/__init__.py

@@ -5,12 +5,13 @@ Provides commands for sending emails and notifications via SMTP.
 Contents:
     * :func:`.send_email.cli_send_email` - Send email with optional HTML and attachments.
     * :func:`.send_notification.cli_send_notification` - Send simple plain-text notification.
+    * :class:`._common.EmailConfigOverrides` - The SMTP options a command line gave, typed.
 """
 
 from __future__ import annotations
 
-from ._common import filter_sentinels
+from ._common import EmailConfigOverrides
 from .send_email import cli_send_email
 from .send_notification import cli_send_notification
 
-__all__ = ["cli_send_email", "cli_send_notification", "filter_sentinels"]
+__all__ = ["EmailConfigOverrides", "cli_send_email", "cli_send_notification"]

{bitranox_template_py_cli-2.3.0 → bitranox_template_py_cli-2.4.0}/src/bitranox_template_py_cli/adapters/cli/commands/email/_common.py

@@ -9,10 +9,10 @@ from __future__ import annotations
 import functools
 import logging
 import os
-from typing import TYPE_CHECKING, Any, NoReturn, cast
+from typing import TYPE_CHECKING, Any, NoReturn
 
-from btx_lib_mail import AttachmentSecurityError
-from pydantic import ValidationError
+from btx_lib_mail import AttachmentSecurityError, SecretSafeModel
+from pydantic import ConfigDict, SecretStr, ValidationError
 
 from bitranox_template_py_cli import __init__conf__
 from bitranox_template_py_cli.adapters.email.config import describe_validation_error
@@ -33,51 +33,79 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
-def filter_sentinels(**kwargs: Any) -> dict[str, Any]:
-    """Filter out None and empty tuple sentinels, converting tuples to lists.
+class EmailConfigOverrides(SecretSafeModel):
+    """The EmailConfig fields the command line overrides; ``None`` means the option was not given.
 
-    Used to prepare CLI option overrides for ``_apply_validated_overrides()``.
-    Removes None values (unset options) and empty tuples (unset multiple options),
-    and converts non-empty tuples to lists for Pydantic compatibility.
+    Each field carries EmailConfig's own name, so a field EmailConfig renames is refused here
+    instead of being passed along unnoticed. The password stays a ``SecretStr`` from the moment
+    the command line hands it over, and a validation error never carries its value, not even in
+    ``errors()`` or ``json()``.
+    """
 
-    Args:
-        **kwargs: Keyword arguments to filter.
+    model_config = ConfigDict(frozen=True, extra="forbid")
+    credential_fields = frozenset({"smtp_password"})
+
+    smtphosts: tuple[str, ...] | None = None
+    smtp_username: str | None = None
+    smtp_password: SecretStr | None = None
+    smtp_use_starttls: bool | None = None
+    smtp_timeout: float | None = None
+    raise_on_missing_attachments: bool | None = None
+    raise_on_invalid_recipient: bool | None = None
+
+    @classmethod
+    def from_cli_options(
+        cls,
+        *,
+        smtp_hosts: tuple[str, ...] = (),
+        smtp_username: str | None = None,
+        smtp_password: str | None = None,
+        use_starttls: bool | None = None,
+        timeout: float | None = None,
+        raise_on_missing_attachments: bool | None = None,
+        raise_on_invalid_recipient: bool | None = None,
+    ) -> EmailConfigOverrides:
+        """Build the overrides from the values Click hands a command.
+
+        Click reports an option that was not given as ``None``, and a ``multiple=True`` option
+        that was not given as an empty tuple; both become ``None`` here.
+
+        Examples:
+            >>> EmailConfigOverrides.from_cli_options(smtp_hosts=(), timeout=5.0).model_dump(exclude_none=True)
+            {'smtp_timeout': 5.0}
+        """
+        return cls(
+            smtphosts=smtp_hosts or None,
+            smtp_username=smtp_username,
+            smtp_password=None if smtp_password is None else SecretStr(smtp_password),
+            smtp_use_starttls=use_starttls,
+            smtp_timeout=timeout,
+            raise_on_missing_attachments=raise_on_missing_attachments,
+            raise_on_invalid_recipient=raise_on_invalid_recipient,
+        )
 
-    Returns:
-        Filtered dict with sentinel values removed and tuples converted to lists.
-    """
-    result: dict[str, Any] = {}
-    for k, v in kwargs.items():
-        if v is None or v == ():
-            continue
-        if isinstance(v, tuple):
-            result[k] = list(cast("tuple[Any, ...]", v))
-        else:
-            result[k] = v
-    return result
-
-
-def apply_validated_overrides(base_config: EmailConfig, overrides: dict[str, Any]) -> EmailConfig:
+
+def apply_validated_overrides(base_config: EmailConfig, overrides: EmailConfigOverrides) -> EmailConfig:
     """Apply overrides with full Pydantic validation.
 
-    Uses model_validate() with a merged dict instead of model_copy(update=...)
-    to ensure Pydantic validators run on all overridden values.
+    Uses model_validate() with a merged mapping instead of model_copy(update=...)
+    to ensure EmailConfig's validators run on all overridden values.
 
     Args:
         base_config: Base EmailConfig to merge overrides into.
-        overrides: Dict of field values to override (already filtered).
+        overrides: The options given on the command line.
 
     Returns:
-        New EmailConfig with overrides applied and validated.
+        ``base_config`` itself when no option was given, else a new EmailConfig with the
+        overrides applied and validated.
 
     Raises:
         ValidationError: When overrides contain invalid values.
     """
-    if not overrides:
+    given = overrides.model_dump(exclude_none=True)
+    if not given:
         return base_config
-    base_dict = base_config.model_dump()
-    merged = {**base_dict, **overrides}
-    return EmailConfig.model_validate(merged)
+    return EmailConfig.model_validate({**base_config.model_dump(), **given})
 
 
 def smtp_config_options(func: Callable[..., Any]) -> Callable[..., Any]:
@@ -337,9 +365,9 @@ def _handle_send_error(
 
 
 __all__ = [
+    "EmailConfigOverrides",
     "apply_validated_overrides",
     "execute_with_email_error_handling",
-    "filter_sentinels",
     "handle_validation_error",
     "load_and_validate_email_config",
     "smtp_config_options",

{bitranox_template_py_cli-2.3.0 → bitranox_template_py_cli-2.4.0}/src/bitranox_template_py_cli/adapters/cli/commands/email/send_email.py

@@ -18,9 +18,9 @@ from ...constants import CLICK_CONTEXT_SETTINGS
 from ...context import get_cli_context
 from ...typed_click import option
 from ._common import (
+    EmailConfigOverrides,
     apply_validated_overrides,
     execute_with_email_error_handling,
-    filter_sentinels,
     handle_validation_error,
     load_and_validate_email_config,
     smtp_config_options,
@@ -112,12 +112,12 @@ def cli_send_email(
 
     with lib_log_rich.runtime.bind(job_id="cli-send-email", extra=extra):
         email_config = load_and_validate_email_config(config, cli_ctx.services.load_email_config_from_dict)
-        overrides = filter_sentinels(
-            smtphosts=smtp_hosts,
+        overrides = EmailConfigOverrides.from_cli_options(
+            smtp_hosts=smtp_hosts,
             smtp_username=smtp_username,
             smtp_password=smtp_password,
-            smtp_use_starttls=use_starttls,
-            smtp_timeout=timeout,
+            use_starttls=use_starttls,
+            timeout=timeout,
             raise_on_missing_attachments=raise_on_missing_attachments,
             raise_on_invalid_recipient=raise_on_invalid_recipient,
         )

{bitranox_template_py_cli-2.3.0 → bitranox_template_py_cli-2.4.0}/src/bitranox_template_py_cli/adapters/cli/commands/email/send_notification.py

@@ -17,9 +17,9 @@ from ...constants import CLICK_CONTEXT_SETTINGS
 from ...context import get_cli_context
 from ...typed_click import option
 from ._common import (
+    EmailConfigOverrides,
     apply_validated_overrides,
     execute_with_email_error_handling,
-    filter_sentinels,
     handle_validation_error,
     load_and_validate_email_config,
     smtp_config_options,
@@ -70,12 +70,12 @@ def cli_send_notification(
 
     with lib_log_rich.runtime.bind(job_id="cli-send-notification", extra=extra):
         email_config = load_and_validate_email_config(config, cli_ctx.services.load_email_config_from_dict)
-        overrides = filter_sentinels(
-            smtphosts=smtp_hosts,
+        overrides = EmailConfigOverrides.from_cli_options(
+            smtp_hosts=smtp_hosts,
             smtp_username=smtp_username,
             smtp_password=smtp_password,
-            smtp_use_starttls=use_starttls,
-            smtp_timeout=timeout,
+            use_starttls=use_starttls,
+            timeout=timeout,
             raise_on_invalid_recipient=raise_on_invalid_recipient,
         )
         try:

{bitranox_template_py_cli-2.3.0 → bitranox_template_py_cli-2.4.0}/tests/test_mail.py

@@ -19,7 +19,7 @@ from btx_lib_mail import ConfMail
 from pydantic import SecretStr
 from pydantic import ValidationError as PydanticValidationError
 
-from bitranox_template_py_cli.adapters.cli.commands.email._common import apply_validated_overrides
+from bitranox_template_py_cli.adapters.cli.commands.email._common import EmailConfigOverrides, apply_validated_overrides
 from bitranox_template_py_cli.adapters.email.sender import (
     EmailConfig,
     load_email_config_from_dict,
@@ -368,10 +368,89 @@ def test_no_rendering_of_the_email_config_shows_the_password(render: Callable[[E
 def test_an_override_keeps_the_configured_password() -> None:
     config = EmailConfig(smtphosts=["smtp.example.com:587"], smtp_username="user", smtp_password=SecretStr(_PASSWORD))
 
-    overridden = apply_validated_overrides(config, {"smtp_timeout": 5.0})
+    overridden = apply_validated_overrides(config, EmailConfigOverrides.from_cli_options(timeout=5.0))
 
     assert overridden.smtp_password is not None
     assert overridden.smtp_password.get_secret_value() == _PASSWORD
+    assert overridden.smtp_timeout == 5.0
+
+
+@pytest.mark.os_agnostic
+def test_no_override_given_returns_the_configuration_itself() -> None:
+    config = EmailConfig(smtphosts=["smtp.example.com:587"])
+
+    assert apply_validated_overrides(config, EmailConfigOverrides.from_cli_options()) is config
+
+
+@pytest.mark.os_agnostic
+def test_an_unset_host_option_keeps_the_hosts_and_a_set_one_replaces_them() -> None:
+    config = EmailConfig(smtphosts=["smtp.example.com:587"])
+
+    unset = apply_validated_overrides(config, EmailConfigOverrides.from_cli_options(smtp_hosts=()))
+    replaced = apply_validated_overrides(
+        config, EmailConfigOverrides.from_cli_options(smtp_hosts=("other.example.com:25", "third.example.com:25"))
+    )
+
+    assert unset.smtphosts == ["smtp.example.com:587"]
+    assert replaced.smtphosts == ["other.example.com:25", "third.example.com:25"]
+
+
+@pytest.mark.os_agnostic
+def test_a_password_given_on_the_command_line_never_renders_from_the_overrides() -> None:
+    overrides = EmailConfigOverrides.from_cli_options(smtp_password=_PASSWORD)
+
+    assert _PASSWORD not in repr(overrides)
+    assert _PASSWORD not in str(overrides.model_dump())
+    assert overrides.smtp_password is not None
+    assert overrides.smtp_password.get_secret_value() == _PASSWORD
+
+
+@pytest.mark.os_agnostic
+def test_an_override_refuses_a_name_that_is_not_an_email_config_field() -> None:
+    """The overrides carry EmailConfig's own field names, so a renamed field cannot pass unnoticed."""
+    with pytest.raises(PydanticValidationError, match="smtp_hosts"):
+        EmailConfigOverrides.model_validate({"smtp_hosts": ["smtp.example.com:587"]})
+
+
+@pytest.mark.os_agnostic
+def test_each_command_line_option_lands_in_its_own_field() -> None:
+    """Every option is distinct from its neighbours, so a swapped parameter shows as a mismatch."""
+    overrides = EmailConfigOverrides.from_cli_options(
+        smtp_hosts=("smtp.example.com:587",),
+        smtp_username="user",
+        smtp_password=_PASSWORD,
+        use_starttls=False,
+        timeout=7.5,
+        raise_on_missing_attachments=True,
+        raise_on_invalid_recipient=False,
+    )
+
+    dumped = overrides.model_dump()
+    secret = dumped.pop("smtp_password")
+
+    assert secret.get_secret_value() == _PASSWORD
+    assert dumped == {
+        "smtphosts": ("smtp.example.com:587",),
+        "smtp_username": "user",
+        "smtp_use_starttls": False,
+        "smtp_timeout": 7.5,
+        "raise_on_missing_attachments": True,
+        "raise_on_invalid_recipient": False,
+    }
+
+
+@pytest.mark.os_agnostic
+def test_a_refused_password_value_stays_out_of_the_error_details() -> None:
+    with pytest.raises(PydanticValidationError) as caught:
+        EmailConfigOverrides.model_validate({"smtp_password": [_PASSWORD]})
+
+    assert _PASSWORD not in str(caught.value.errors())
+    assert _PASSWORD not in caught.value.json()
+
+
+@pytest.mark.os_agnostic
+def test_every_override_names_an_email_config_field() -> None:
+    assert set(EmailConfigOverrides.model_fields) <= set(EmailConfig.model_fields)
 
 
 # ======================== load_email_config_from_dict ========================