bitranox-template-py-cli 2.0.1__tar.gz → 2.1.0__tar.gz

{bitranox_template_py_cli-2.0.1 → bitranox_template_py_cli-2.1.0}/.env.example

@@ -101,6 +101,20 @@ GITHUB_TOKEN=
 # .env: EMAIL__LOCAL_HOSTNAME=mail.example.com
 # EMAIL__LOCAL_HOSTNAME=mail.example.com
 
+# Purpose: Upper bound in seconds for one SMTP session (connect to QUIT); 0 for none
+# Type: float
+# Default: 0 (none)
+# Environment Variable: BITRANOX_TEMPLATE_PY_CLI___EMAIL__DELIVERY_DEADLINE=300
+# .env: EMAIL__DELIVERY_DEADLINE=300
+# EMAIL__DELIVERY_DEADLINE=300
+
+# Purpose: Most recipients one send accepts; 0 for no limit
+# Type: integer
+# Default: 1000
+# Environment Variable: BITRANOX_TEMPLATE_PY_CLI___EMAIL__RECIPIENT_MAX_COUNT=1000
+# .env: EMAIL__RECIPIENT_MAX_COUNT=1000
+# EMAIL__RECIPIENT_MAX_COUNT=1000
+
 # Purpose: Raise FileNotFoundError when attachment files are missing
 # Type: boolean (true/false)
 # Default: true

{bitranox_template_py_cli-2.0.1 → bitranox_template_py_cli-2.1.0}/CHANGELOG.md

@@ -6,6 +6,27 @@ the [Keep a Changelog](https://keepachangelog.com/) format.
 
 ## [Unreleased]
 
+## [2.1.0] 2026-10-06 15:37:27
+
+### Added
+- **Three email limits from btx_lib_mail 4.0.0 are configurable**: `[email] delivery_deadline`
+  (an upper bound in seconds for one SMTP session; the field is `smtp_delivery_deadline`),
+  `[email] recipient_max_count` (default 1000) and `[email.attachments] max_count` (default
+  100). A value of 0 means no limit, as `max_size_bytes = 0` already did. Shipped in
+  `50-mail.toml`, `.env.example` and the module reference.
+
+### Changed
+- **Requires `btx_lib_mail>=4.0.0`.** Effects a user of the email commands can see: the
+  Windows dangerous extensions (`.exe`, `.bat`, `.ps1`, ...) are refused on every platform by
+  default and the POSIX ones on Windows; a sender or recipient longer than RFC 5321 allows is
+  refused; a subject with a control character or over 4096 characters is refused; an
+  attachment swapped after its checks is refused; a delivery error is a `DeliveryError` (still
+  a `RuntimeError`). See the btx_lib_mail 4.0.0 changelog for the full list.
+
+### Removed
+- **`EmailConfig`'s own SMTP host validator.** `ConfMail` checks every host's syntax (port
+  range, IPv6 brackets) itself since btx_lib_mail 3.0.1; the messages are unchanged.
+
 ## [2.0.1] 2026-10-06 13:09:50
 
 Re-release of 2.0.0, which was tagged but never published: PyPI rejected the upload because

{bitranox_template_py_cli-2.0.1 → bitranox_template_py_cli-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bitranox_template_py_cli
-Version: 2.0.1
+Version: 2.1.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
@@ -21,7 +21,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
-Requires-Dist: btx-lib-mail>=3.0.1
+Requires-Dist: btx-lib-mail>=4.0.0
 Requires-Dist: click>=8.5.0
 Requires-Dist: lib-cli-exit-tools>=2.4.0
 Requires-Dist: lib-layered-config>=7.0.1
@@ -286,6 +286,7 @@ use_starttls = true
 starttls_verify = true   # false accepts any certificate: only for a known internal relay
 timeout = 60.0
 # local_hostname = "mail.example.com"   # EHLO name; set it where reverse DNS is slow
+# delivery_deadline = 300               # upper bound in seconds for one SMTP session; 0 = none
 ```
 
 A key `[email]` or `[email.attachments]` does not know is refused (exit 78,
@@ -378,8 +379,8 @@ from bitranox_template_py_cli.composition import send_email, send_notification
 
 # Configure email. EmailConfig is a btx_lib_mail ConfMail, so in Python the fields use the
 # library's names (smtphosts, smtp_use_starttls, smtp_timeout, smtp_starttls_verify,
-# smtp_local_hostname); configuration files keep their keys (smtp_hosts, use_starttls, timeout,
-# starttls_verify, local_hostname). smtp_password is a SecretStr: it prints as
+# smtp_local_hostname, smtp_delivery_deadline); configuration files keep their keys (smtp_hosts,
+# use_starttls, timeout, starttls_verify, local_hostname, delivery_deadline). smtp_password is a SecretStr: it prints as
 # '**********' in logs, reprs and dumps, and config.smtp_password.get_secret_value() returns
 # the plain text.
 config = EmailConfig(

{bitranox_template_py_cli-2.0.1 → bitranox_template_py_cli-2.1.0}/README.md

@@ -231,6 +231,7 @@ use_starttls = true
 starttls_verify = true   # false accepts any certificate: only for a known internal relay
 timeout = 60.0
 # local_hostname = "mail.example.com"   # EHLO name; set it where reverse DNS is slow
+# delivery_deadline = 300               # upper bound in seconds for one SMTP session; 0 = none
 ```
 
 A key `[email]` or `[email.attachments]` does not know is refused (exit 78,
@@ -323,8 +324,8 @@ from bitranox_template_py_cli.composition import send_email, send_notification
 
 # Configure email. EmailConfig is a btx_lib_mail ConfMail, so in Python the fields use the
 # library's names (smtphosts, smtp_use_starttls, smtp_timeout, smtp_starttls_verify,
-# smtp_local_hostname); configuration files keep their keys (smtp_hosts, use_starttls, timeout,
-# starttls_verify, local_hostname). smtp_password is a SecretStr: it prints as
+# smtp_local_hostname, smtp_delivery_deadline); configuration files keep their keys (smtp_hosts,
+# use_starttls, timeout, starttls_verify, local_hostname, delivery_deadline). smtp_password is a SecretStr: it prints as
 # '**********' in logs, reprs and dumps, and config.smtp_password.get_secret_value() returns
 # the plain text.
 config = EmailConfig(

{bitranox_template_py_cli-2.0.1 → bitranox_template_py_cli-2.1.0}/docs/systemdesign/module_reference.md

@@ -337,6 +337,8 @@ column).
 | `smtp_starttls_verify`         | `bool`              | `True`  | `starttls_verify`              | Verify the server certificate after STARTTLS                     |
 | `smtp_timeout`                 | `float`             | `30.0`  | `timeout`                      | Socket timeout in seconds                                        |
 | `smtp_local_hostname`          | `str \| None`       | `None`  | `local_hostname`               | Host name announced in EHLO; `None` looks it up once per process |
+| `smtp_delivery_deadline`       | `float \| None`     | `None`  | `delivery_deadline`            | Upper bound in seconds for one SMTP session; `None` for none     |
+| `recipient_max_count`          | `int \| None`       | `1000`  | `recipient_max_count`          | Most recipients one send accepts; `None` lifts the limit         |
 | `raise_on_missing_attachments` | `bool`              | `True`  | `raise_on_missing_attachments` | Raise on missing attachment files                                |
 | `raise_on_invalid_recipient`   | `bool`              | `True`  | `raise_on_invalid_recipient`   | Raise on invalid recipient addresses                             |
 
@@ -345,10 +347,11 @@ column).
 | Field                                    | Type                      | Default      | File key (`[email.attachments]`) | Description                                             |
 |------------------------------------------|---------------------------|--------------|----------------------------------|---------------------------------------------------------|
 | `attachment_allowed_extensions`          | `frozenset[str] \| None`  | `None`       | `allowed_extensions`             | Whitelist of allowed extensions                         |
-| `attachment_blocked_extensions`          | `frozenset[str]`          | OS defaults  | `blocked_extensions`             | Blacklist of blocked extensions                         |
+| `attachment_blocked_extensions`          | `frozenset[str]`          | POSIX + Win  | `blocked_extensions`             | Blacklist of blocked extensions (both lists, every OS)  |
 | `attachment_allowed_directories`         | `frozenset[Path] \| None` | `None`       | `allowed_directories`            | Whitelist of allowed source directories                 |
 | `attachment_blocked_directories`         | `frozenset[Path]`         | OS defaults  | `blocked_directories`            | Blacklist of blocked directories                        |
 | `attachment_max_size_bytes`              | `int \| None`             | `26_214_400` | `max_size_bytes`                 | Maximum file size (25 MiB), `None` to disable           |
+| `attachment_max_count`                   | `int \| None`             | `100`        | `max_count`                      | Most attachments one send accepts, `None` to disable    |
 | `attachment_allow_symlinks`              | `bool`                    | `False`      | `allow_symlinks`                 | Whether symlinks are permitted                          |
 | `attachment_raise_on_security_violation` | `bool`                    | `True`       | `raise_on_security_violation`    | Raise or skip on security violation                     |
 | `attachment_allow_empty_blocklists`      | `bool`                    | `False`      | not exposed                      | Allow an empty blocked set (blocks nothing) from Python |
@@ -359,13 +362,13 @@ lib_layered_config is the only reader of configuration: it merges every layer (t
 defaults, the app, host and user files, `.env`, the environment, `--set`) into one mapping.
 `load_email_config_from_dict()` turns that mapping's `[email]` section into an `EmailConfig`:
 
-- the five keys in the third column that differ from the field names are mapped;
+- the six keys in the third column that differ from the field names are mapped;
 - `[email.attachments]` keys become `attachment_<key>`;
 - a key that is not listed is refused (exit 78, `email.<key>: unknown key`), whatever layer it came from;
 - blank text means "not configured"; a single host or address string is a one-entry list;
 - an empty attachment list (`[]` or a blank string) means the library's defaults, and any other
   value that is not a list, such as a comma-separated string, is refused, as is a blank entry;
-- `max_size_bytes = 0` means no size limit.
+- a limit of 0 (`max_size_bytes`, `max_count`, `recipient_max_count`, `delivery_deadline`) means no limit.
 
 `describe_validation_error()` renders a refusal as one `email.<file key>: <reason>` line per
 problem, never with the refused value.

{bitranox_template_py_cli-2.0.1 → bitranox_template_py_cli-2.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "bitranox_template_py_cli"
-version = "2.0.1"
+version = "2.1.0"
 description = "Template CLI application with configuration management and structured logging"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -12,7 +12,7 @@ dependencies = [
     "lib_log_rich>=6.3.9",
     "python-dotenv>=1.2.4",
     "lib_layered_config>=7.0.1",
-    "btx_lib_mail>=3.0.1",
+    "btx_lib_mail>=4.0.0",
     "pydantic>=2.13.5",
     "orjson>=3.12.0",
 ]

{bitranox_template_py_cli-2.0.1 → bitranox_template_py_cli-2.1.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.0.1"
+version = "2.1.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.0.1 → bitranox_template_py_cli-2.1.0}/src/bitranox_template_py_cli/adapters/config/defaultconfig.d/50-mail.toml

@@ -110,6 +110,23 @@ starttls_verify = true
 #   qualified name here.
 local_hostname = ""
 
+# Purpose: Upper bound in seconds for one SMTP session, from the connect to QUIT
+# Type: float, or 0 for no deadline
+# Default: 0 (none; only the socket timeout bounds each read or write)
+# Environment Variable: BITRANOX_TEMPLATE_PY_CLI___EMAIL__DELIVERY_DEADLINE=300
+# .env: EMAIL__DELIVERY_DEADLINE=300
+# Note: The socket timeout restarts with every byte, so a server answering one byte at a
+#   time can hold a session open indefinitely; past the deadline that host counts as failed.
+delivery_deadline = 0
+
+# Purpose: Most recipients one send accepts (counted after duplicates are dropped)
+# Type: integer, or 0 for no limit
+# Default: 1000
+# Environment Variable: BITRANOX_TEMPLATE_PY_CLI___EMAIL__RECIPIENT_MAX_COUNT=1000
+# .env: EMAIL__RECIPIENT_MAX_COUNT=1000
+# Note: More recipients are refused before anything is delivered
+recipient_max_count = 1000
+
 # Purpose: Behavior when attachment files are missing
 # Type: boolean
 # Default: true (raise FileNotFoundError)
@@ -152,9 +169,9 @@ allowed_extensions = []
 
 # Purpose: Blacklist of blocked file extensions (ignored when allowed_extensions is set)
 # Type: array of strings
-# Default: [] (the library's defaults apply: btx_lib_mail DANGEROUS_EXTENSIONS_POSIX /
-#   DANGEROUS_EXTENSIONS_WINDOWS; paths matching SENSITIVE_PATH_PATTERNS such as /.ssh/ are
-#   always refused)
+# Default: [] (the library's defaults apply: btx_lib_mail DANGEROUS_EXTENSIONS_POSIX plus
+#   DANGEROUS_EXTENSIONS_WINDOWS on every platform; paths matching SENSITIVE_PATH_PATTERNS such
+#   as /.ssh/ are always refused)
 # Environment Variable: BITRANOX_TEMPLATE_PY_CLI___EMAIL__ATTACHMENTS__BLOCKED_EXTENSIONS='[".exe",".bat",".cmd"]'
 # .env: EMAIL__ATTACHMENTS__BLOCKED_EXTENSIONS=[".exe",".bat",".cmd"] (unquoted)
 # A comma-separated value is NOT a list: it arrives as one string and is refused
@@ -197,6 +214,14 @@ blocked_directories = []
 # Note: Set to 0 to disable size checking entirely
 max_size_bytes = 26214400
 
+# Purpose: Most attachments one send accepts
+# Type: integer, or 0 for no limit
+# Default: 100
+# Environment Variable: BITRANOX_TEMPLATE_PY_CLI___EMAIL__ATTACHMENTS__MAX_COUNT=100
+# .env: EMAIL__ATTACHMENTS__MAX_COUNT=100
+# Note: More attachments are refused before any file is checked or anything is delivered
+max_count = 100
+
 # Purpose: Whether to allow symbolic links as attachments
 # Type: boolean
 # Default: false (symlinks are rejected)

{bitranox_template_py_cli-2.0.1 → bitranox_template_py_cli-2.1.0}/src/bitranox_template_py_cli/adapters/email/config.py

@@ -3,7 +3,7 @@
 lib_layered_config is the only reader of configuration. It merges every layer (the shipped
 defaults, the app, host and user files, ``.env``, the environment and ``--set``) into one
 mapping, and :func:`load_email_config_from_dict` turns that mapping's ``[email]`` section into
-:class:`EmailConfig`. Operators keep writing the file keys they always wrote; five of them
+:class:`EmailConfig`. Operators keep writing the file keys they always wrote; six of them
 differ from the field names code reads (``FILE_KEY_TO_FIELD``). A key that is not a file key
 is refused, so a typo cannot leave a setting silently at its default.
 """
@@ -14,7 +14,7 @@ import re
 from collections.abc import Mapping
 from typing import TYPE_CHECKING, Any, cast
 
-from btx_lib_mail import ConfMail, validate_email_address, validate_smtp_host
+from btx_lib_mail import ConfMail, validate_email_address
 from pydantic import ConfigDict, Field, SecretStr, ValidationError, field_validator
 
 if TYPE_CHECKING:
@@ -34,6 +34,7 @@ FILE_KEY_TO_FIELD: dict[str, str] = {
     "timeout": "smtp_timeout",
     "starttls_verify": "smtp_starttls_verify",
     "local_hostname": "smtp_local_hostname",
+    "delivery_deadline": "smtp_delivery_deadline",
 }
 _FIELD_TO_FILE_KEY: dict[str, str] = {field: key for key, field in FILE_KEY_TO_FIELD.items()}
 
@@ -47,6 +48,7 @@ SECTION_KEYS = frozenset(
         "smtp_password",
         "raise_on_missing_attachments",
         "raise_on_invalid_recipient",
+        "recipient_max_count",
         _ATTACHMENTS,
     }
 )
@@ -59,6 +61,7 @@ ATTACHMENT_KEYS = frozenset(
         "allowed_directories",
         "blocked_directories",
         "max_size_bytes",
+        "max_count",
         "allow_symlinks",
         "raise_on_security_violation",
     }
@@ -74,6 +77,9 @@ _BLANK_TEXT_MEANS_UNSET = frozenset(
 _EMPTY_LIST_MEANS_DEFAULT = frozenset(
     {"allowed_extensions", "blocked_extensions", "allowed_directories", "blocked_directories"}
 )
+#: Limits whose 0 means "no limit". ConfMail refuses 0 and lifts a limit with None, which a
+#: TOML file or an environment variable cannot write.
+_ZERO_MEANS_NO_LIMIT = frozenset({"max_size_bytes", "max_count", "recipient_max_count", "delivery_deadline"})
 #: The refusal of a blank entry in an attachment list.
 _BLANK_ENTRY = ValueError("an entry is blank; remove it")
 #: The form an attachment list must take, named by the refusal of any other form. A
@@ -146,16 +152,6 @@ class EmailConfig(ConfMail):
             return [value] if value.strip() else []
         return value
 
-    @field_validator("smtphosts")
-    @classmethod
-    def _check_hosts(cls, value: list[str]) -> list[str]:
-        # ConfMail refuses userinfo, a path and control characters; the port range and the
-        # IPv6 brackets are checked only by validate_smtp_host, so a typo surfaces at load
-        # time rather than at the first delivery.
-        for host in value:
-            validate_smtp_host(host)
-        return value
-
     @field_validator("from_address")
     @classmethod
     def _check_from_address(cls, value: str | None) -> str | None:
@@ -273,10 +269,10 @@ def _means_unset(key: str, value: object) -> bool:
 
 
 def _field_value(key: str, value: object) -> object:
-    """A lone host or address becomes a one-entry list; a size limit of 0 means no limit."""
+    """A lone host or address becomes a one-entry list; a limit of 0 means no limit."""
     if key in _ONE_OR_MANY and isinstance(value, str):
         return [value]
-    if key == "max_size_bytes" and type(value) in (int, float) and value == 0:
+    if key in _ZERO_MEANS_NO_LIMIT and type(value) in (int, float) and value == 0:
         return None
     return value
 

{bitranox_template_py_cli-2.0.1 → bitranox_template_py_cli-2.1.0}/tests/test_email_config_translation.py

@@ -108,6 +108,37 @@ def test_a_size_limit_of_zero_means_no_limit() -> None:
     assert _load({"attachments": {"max_size_bytes": 0}}).attachment_max_size_bytes is None
 
 
+@pytest.mark.os_agnostic
+@pytest.mark.parametrize(
+    ("email", "field"),
+    [
+        ({"recipient_max_count": 0}, "recipient_max_count"),
+        ({"delivery_deadline": 0}, "smtp_delivery_deadline"),
+        ({"delivery_deadline": 0.0}, "smtp_delivery_deadline"),
+        ({"attachments": {"max_count": 0}}, "attachment_max_count"),
+    ],
+    ids=["recipient_max_count", "delivery_deadline", "delivery_deadline_float", "attachments.max_count"],
+)
+def test_every_other_limit_of_zero_means_no_limit(email: dict[str, Any], field: str) -> None:
+    assert getattr(_load(email), field) is None
+
+
+@pytest.mark.os_agnostic
+def test_the_limits_reach_their_fields() -> None:
+    config = _load({"recipient_max_count": 5, "delivery_deadline": 120, "attachments": {"max_count": 3}})
+
+    assert (config.recipient_max_count, config.smtp_delivery_deadline, config.attachment_max_count) == (5, 120.0, 3)
+
+
+@pytest.mark.os_agnostic
+def test_a_negative_deadline_is_named_by_its_file_key() -> None:
+    (line,) = _problems({"delivery_deadline": -1})
+
+    assert line.startswith("email.delivery_deadline: ")
+    assert "smtp_delivery_deadline" not in line
+    assert "unknown key" not in line
+
+
 @pytest.mark.os_agnostic
 @pytest.mark.parametrize(
     ("email", "line"),