bitranox-template-py-cli 1.7.1__tar.gz → 1.7.2__tar.gz

{bitranox_template_py_cli-1.7.1 → bitranox_template_py_cli-1.7.2}/CHANGELOG.md

@@ -6,6 +6,15 @@ the [Keep a Changelog](https://keepachangelog.com/) format.
 
 ## [Unreleased]
 
+## [1.7.2] 2026-09-12 02:11:47
+
+### Fixed
+- **`--set` overrides now report the CLI as their source.** `Config.with_overrides` returns the
+  merged data with the ORIGINAL provenance map by design, so an overridden key kept naming the
+  file it replaced and `config` sent a reader to a file holding the old value. The override path
+  rebuilds provenance, naming layer `cli` with no path for exactly the keys `--set` supplied and
+  leaving every other key's source alone.
+
 ## [1.7.1] 2026-08-01 01:02:45
 
 Re-release of 1.7.0, which was tagged but never published: PyPI rejected the upload because

{bitranox_template_py_cli-1.7.1 → bitranox_template_py_cli-1.7.2}/Makefile

@@ -1,4 +1,4 @@
-# BMK MAKEFILE 3.14.0
+# BMK MAKEFILE 3.17.0
 # do not alter this file - it might be overwritten on new versions of BMK
 # if You want to alter it, remove the first line # BMK MAKEFILE 1.0 - then it is a custom makefile and will not be overwritten
 # bmk Makefile - thin wrapper using `uv tool upgrade` for persistent bmk
@@ -186,16 +186,50 @@ endif
 # BMK_MIN floors the FALLBACK install. The upgrade path does not consult it: uv re-resolves
 # the requirement recorded at install time, which is itself a `bmk>=...`, so it always lands
 # on the newest release and clears the floor anyway.
-BMK_MIN := 3.14.0
+BMK_MIN := 3.17.0
 
 # Absent env, missing check, or damaged env - all three mean "do not upgrade, rebuild".
 # `test -x` keeps a fresh machine quiet: there is no interpreter to run yet.
 BMK_INTACT := $(if $(BMK_PY),test -x "$(BMK_PY)" && "$(BMK_PY)" -m bmk_selfcheck,false)
 
+# The env this recipe mutates is shared by EVERY repo on the machine, so the mutation has to
+# wait for the bmk processes running out of it. Every bmk started from that env holds a
+# SHARED lock on <uv tool dir>/.bmk-tool.lock for its whole lifetime; these wrappers take
+# the same lock EXCLUSIVE for the length of the upgrade. Without it, a make here deleted the
+# site-packages out from under a bmk minutes into a test suite in an UNRELATED repo, and it
+# surfaced as an ImportError inside bmk's OWN dependencies that cleared on a re-run - so it
+# read as a flake rather than as the environment vanishing mid-gate.
+#
+# `bmk_toollock` is a second stdlib-only TOP-LEVEL module bmk ships, run on the tool env's
+# own interpreter. That is not circular: a uv tool env's bin/python is a SYMLINK to a base
+# interpreter OUTSIDE the tool dir, so the stdlib the guard runs on is not part of the tree
+# uv is about to replace, and the guard is read and compiled before uv is ever spawned.
+#
+# NOT uv's own <uv tool dir>/.lock, which uv does honour: `uv tool upgrade` and `uv tool
+# list` block on it too (measured), and the upgrade runs before every target - so a
+# gate-lifetime shared lock there would make every make on the machine, and every unrelated
+# `uv tool install`, wait for the longest-running gate.
+#
+# $(wildcard) rather than a shell test: on a machine with no tool env yet these expand to
+# NOTHING and the install runs bare, which is exactly what a first install needs.
+#
+# The bounded wait is load-bearing in both directions. An unbounded one would serialise
+# every repo's make behind the longest gate on the machine. A SKIPPED upgrade costs nothing
+# (the next make picks it up), so the upgrade skips. The REPAIR may not skip: proceeding
+# would leave a damaged env in place, so it fails and drops through to the retry.
+#
+# The LAST attempt is deliberately NEVER guarded, and a test pins that. The guard lives
+# inside the env being repaired, so on the path where that env is absent or broken the guard
+# may be broken too; an unguarded last resort is what stops a defective guard from making
+# `make` unrunnable in every repo at once. If bmk_toollock ever falls out of the wheel, every
+# make everywhere drops to a full reinstall - there is a packaging test for exactly that.
+BMK_LOCK := $(if $(wildcard $(BMK_PY)),"$(BMK_PY)" -m bmk_toollock --exclusive --timeout 10 --on-timeout skip --,)
+BMK_LOCK_REPAIR := $(if $(wildcard $(BMK_PY)),"$(BMK_PY)" -m bmk_toollock --exclusive --timeout 60 --on-timeout fail --,)
+
 .PHONY: _ensure_bmk
 _ensure_bmk:
-	@$(BMK_INTACT) && uv tool upgrade bmk \
-	  || uv tool install --reinstall --force "bmk>=$(BMK_MIN)" \
+	@$(BMK_INTACT) && $(BMK_LOCK) uv tool upgrade bmk \
+	  || $(BMK_LOCK_REPAIR) uv tool install --reinstall --force "bmk>=$(BMK_MIN)" \
 	  || uv tool install --reinstall --force "bmk>=$(BMK_MIN)"
 
 # ──────────────────────────────────────────────────────────────

{bitranox_template_py_cli-1.7.1 → bitranox_template_py_cli-1.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: bitranox_template_py_cli
-Version: 1.7.1
+Version: 1.7.2
 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
@@ -25,30 +25,30 @@ Requires-Dist: btx-lib-mail>=1.5.2
 Requires-Dist: lib-cli-exit-tools>=2.3.4
 Requires-Dist: lib-layered-config>=5.6.2
 Requires-Dist: lib-log-rich>=6.3.7
-Requires-Dist: orjson>=3.11.9
-Requires-Dist: pydantic>=2.13.4
-Requires-Dist: rich-click>=1.9.8
+Requires-Dist: orjson>=3.12.0
+Requires-Dist: pydantic>=2.13.5
+Requires-Dist: rich-click>=1.9.9
 Provides-Extra: dev
 Requires-Dist: bandit>=1.9.4; extra == 'dev'
-Requires-Dist: build>=1.5.0; extra == 'dev'
-Requires-Dist: click>=8.4.2; extra == 'dev'
-Requires-Dist: httpx2>=2.9.1; extra == 'dev'
-Requires-Dist: hypothesis>=6.164.0; extra == 'dev'
-Requires-Dist: import-linter>=2.13; extra == 'dev'
+Requires-Dist: build>=1.6.1; extra == 'dev'
+Requires-Dist: click>=8.5.0; extra == 'dev'
+Requires-Dist: httpx2>=2.12.0; extra == 'dev'
+Requires-Dist: hypothesis>=6.168.0; extra == 'dev'
+Requires-Dist: import-linter>=2.15; extra == 'dev'
 Requires-Dist: jaraco-context>=6.1.2; extra == 'dev'
 Requires-Dist: pip-audit>=2.10.1; extra == 'dev'
 Requires-Dist: pynacl>=1.6.2; extra == 'dev'
-Requires-Dist: pyright[nodejs]>=1.1.411; extra == 'dev'
+Requires-Dist: pyright[nodejs]>=1.1.414; extra == 'dev'
 Requires-Dist: pytest-cov>=7.1.0; extra == 'dev'
 Requires-Dist: pytest>=9.1.1; extra == 'dev'
 Requires-Dist: python-multipart>=0.0.32; extra == 'dev'
 Requires-Dist: rtoml>=0.13.0; extra == 'dev'
-Requires-Dist: ruff>=0.16.1; extra == 'dev'
+Requires-Dist: ruff>=0.16.7; extra == 'dev'
 Requires-Dist: textual>=8.2.8; extra == 'dev'
 Requires-Dist: twine>=7.0.0; extra == 'dev'
 Requires-Dist: urllib3>=2.7.0; extra == 'dev'
-Requires-Dist: virtualenv>=21.7.1; extra == 'dev'
-Requires-Dist: wheel>=0.47.0; extra == 'dev'
+Requires-Dist: virtualenv>=21.7.9; extra == 'dev'
+Requires-Dist: wheel>=0.48.0; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # bitranox_template_py_cli

{bitranox_template_py_cli-1.7.1 → bitranox_template_py_cli-1.7.2}/pyproject.toml

@@ -1,17 +1,17 @@
 [project]
 name = "bitranox_template_py_cli"
-version = "1.7.1"
+version = "1.7.2"
 description = "Template CLI application with configuration management and structured logging"
 readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [
-    "rich-click>=1.9.8",
+    "rich-click>=1.9.9",
     "lib_cli_exit_tools>=2.3.4",
     "lib_log_rich>=6.3.7",
     "lib_layered_config>=5.6.2",
     "btx_lib_mail>=1.5.2",
-    "pydantic>=2.13.4",
-    "orjson>=3.11.9",
+    "pydantic>=2.13.5",
+    "orjson>=3.12.0",
 ]
 license = { text = "MIT" }
 authors = [{ name = "bitranox", email = "bitranox@gmail.com" }]
@@ -48,13 +48,13 @@ Issues = "https://github.com/bitranox/bitranox_template_py_cli/issues"
 dev = [
   "pytest>=9.1.1",
   "pytest-cov>=7.1.0",
-  "hypothesis>=6.164.0",
-  "ruff>=0.16.1",
-  "pyright[nodejs]>=1.1.411",
+  "hypothesis>=6.168.0",
+  "ruff>=0.16.7",
+  "pyright[nodejs]>=1.1.414",
   "bandit>=1.9.4",
   # 1.5.1 was yanked upstream (unintended breaking changes), so 1.5.0 is the newest usable
   # release; a >=1.5.1 floor has ZERO candidates and makes this extra unresolvable.
-  "build>=1.5.0",
+  "build>=1.6.1",
   "twine>=7.0.0",
   # codecov-cli is disabled, not dropped: it requires click<8.3.0, which drags click back to
   # 8.2.1 - the version with CVE-2026-7246 (command injection in click.edit(), fixed in 8.3.3).
@@ -65,17 +65,17 @@ dev = [
   # "codecov-cli>=11.2.8",
   "pip-audit>=2.10.1",
   "textual>=8.2.8",
-  "import-linter>=2.13",
+  "import-linter>=2.15",
   "rtoml>=0.13.0",
-  "httpx2>=2.9.1",
+  "httpx2>=2.12.0",
   # Transitive CVE pins
-  "click>=8.4.2",                # CVE-2026-7246
+  "click>=8.5.0",                # CVE-2026-7246
   "jaraco-context>=6.1.2",       # CVE-2025-23949
   "python-multipart>=0.0.32",    # CVE-2025-24486
-  "wheel>=0.47.0",               # CVE-2025-24049
+  "wheel>=0.48.0",               # CVE-2025-24049
   "pynacl>=1.6.2",               # CVE-2025-69277
   "urllib3>=2.7.0",              # CVE-2025-66471, CVE-2025-66418
-  "virtualenv>=21.7.1",         # CVE-2025-22702
+  "virtualenv>=21.7.9",         # CVE-2025-22702
 ]
 
 [project.scripts]
@@ -83,7 +83,7 @@ bitranox_template_py_cli = "bitranox_template_py_cli.entry:main"
 bitranox-template-py-cli = "bitranox_template_py_cli.entry:main"
 
 [build-system]
-requires = ["hatchling>=1.31.0"]
+requires = ["hatchling>=1.32.0"]
 build-backend = "hatchling.build"
 
 [tool.hatch.metadata]

{bitranox_template_py_cli-1.7.1 → bitranox_template_py_cli-1.7.2}/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 = "1.7.1"
+version = "1.7.2"
 #: Repository homepage presented to users.
 homepage = "https://github.com/bitranox/bitranox_template_py_cli"
 #: Author attribution surfaced in CLI output.

{bitranox_template_py_cli-1.7.1 → bitranox_template_py_cli-1.7.2}/src/bitranox_template_py_cli/adapters/cli/safe_console.py

@@ -64,13 +64,19 @@ ASCII_FALLBACKS: Final[dict[str, str]] = {
 _UNIVERSAL_ENCODINGS: Final[frozenset[str]] = frozenset({"utf-8", "utf8", "utf-16", "utf16", "utf-32", "utf32"})
 
 
-def _stream_encoding(file: IO[Any] | None) -> str | None:
+def _stream_encoding(file: IO[Any] | None, *, err: bool = False) -> str | None:
     """Return the target stream's encoding, or None when it cannot be determined.
 
     An unknown encoding means the caller gets the original text: guessing would
     degrade output that may well have been fine.
+
+    With no explicit `file` the answer comes from ``sys.stdout``/``sys.stderr``,
+    which is what :func:`click.echo` resolves its own default target from. click
+    exposes no supported way to ask for that stream: ``get_text_stream`` was
+    deprecated in click 8.5.0 and is removed in 9.0, its documented replacement
+    being to let ``echo`` resolve the stream itself.
     """
-    stream = file if file is not None else click.get_text_stream("stdout")
+    stream = file if file is not None else (sys.stderr if err else sys.stdout)
     encoding = getattr(stream, "encoding", None)
     return encoding if isinstance(encoding, str) else None
 
@@ -135,8 +141,7 @@ def echo(message: object = "", *, file: IO[Any] | None = None, err: bool = False
     Writes to the given stream.
     """
     text = message if isinstance(message, str) else str(message)
-    target = file if file is not None else click.get_text_stream("stderr" if err else "stdout")
-    click.echo(encode_safe(text, _stream_encoding(target)), file=target, nl=nl)
+    click.echo(encode_safe(text, _stream_encoding(file, err=err)), file=file, err=err, nl=nl)
 
 
 class _SafeWriter:

{bitranox_template_py_cli-1.7.1 → bitranox_template_py_cli-1.7.2}/src/bitranox_template_py_cli/adapters/config/overrides.py

@@ -2,13 +2,22 @@
 
 from __future__ import annotations
 
+from collections.abc import Iterator, Mapping
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, cast
 
 import orjson
+from lib_layered_config import Config
 
 if TYPE_CHECKING:
-    from lib_layered_config import Config
+    from lib_layered_config.domain.config import SourceInfo
+
+CLI_LAYER = "cli"
+"""Provenance layer recorded for a value that came from ``--set``.
+
+It is not one of the library's file layers because it names no file: the
+value was typed on the command line and there is nothing to open.
+"""
 
 CoercedValue = str | int | float | bool | None | list[object] | dict[str, object]
 """Union of types that :func:`coerce_value` can produce."""
@@ -145,6 +154,53 @@ def _nest_override(target: dict[str, dict[str, object]], override: ConfigOverrid
     node[override.key_path[-1]] = override.value
 
 
+def _dotted_keys(data: Mapping[str, object], prefix: str = "") -> Iterator[str]:
+    """Yield every leaf key of a nested mapping in dotted form.
+
+    Args:
+        data: The nested mapping to walk.
+        prefix: Dotted path accumulated by the caller, ending in a dot.
+
+    Yields:
+        One dotted path per leaf value.
+
+    Example:
+        >>> sorted(_dotted_keys({"a": {"b": 1, "c": {"d": 2}}}))
+        ['a.b', 'a.c.d']
+    """
+    for key, value in data.items():
+        path = f"{prefix}{key}"
+        if isinstance(value, Mapping):
+            yield from _dotted_keys(cast("Mapping[str, object]", value), f"{path}.")
+        else:
+            yield path
+
+
+def _provenance_naming_the_cli(
+    config: Config, merged_as_dict: Mapping[str, object], overridden: frozenset[str]
+) -> dict[str, SourceInfo]:
+    """Copy a Config's provenance, relabelling the keys an override replaced.
+
+    Args:
+        config: The Config the values came from, holding the original map.
+        merged_as_dict: The merged Config's own mapping, walked for the full
+            key set. Passed in already computed, because the caller needs the
+            same mapping to build the merged ``Config``.
+        overridden: Dotted keys that ``--set`` supplied.
+
+    Returns:
+        A provenance map naming the CLI for overridden keys and the original
+        source for every other one.
+    """
+    provenance: dict[str, SourceInfo] = {}
+    for dotted in _dotted_keys(merged_as_dict):
+        if dotted in overridden:
+            provenance[dotted] = {"layer": CLI_LAYER, "path": None, "key": dotted}
+        elif (origin := config.origin(dotted)) is not None:
+            provenance[dotted] = origin
+    return provenance
+
+
 def apply_overrides(config: Config, raw_overrides: tuple[str, ...]) -> Config:
     """Deep-merge CLI overrides into a Config instance.
 
@@ -168,6 +224,8 @@ def apply_overrides(config: Config, raw_overrides: tuple[str, ...]) -> Config:
         >>> result = apply_overrides(cfg, ("s.k=2",))
         >>> result["s"]["k"]
         2
+        >>> result.origin("s.k")["layer"]
+        'cli'
         >>> apply_overrides(cfg, ()) is cfg
         True
     """
@@ -175,14 +233,23 @@ def apply_overrides(config: Config, raw_overrides: tuple[str, ...]) -> Config:
         return config
 
     overrides: dict[str, dict[str, object]] = {}
+    overridden: set[str] = set()
     for raw in raw_overrides:
         parsed = parse_override(raw)
         _nest_override(overrides, parsed)
+        overridden.add(".".join((parsed.section, *parsed.key_path)))
 
-    return config.with_overrides(overrides)
+    # Rebuilt rather than returned straight from with_overrides, which shares
+    # the original provenance map by design: the merged value is the CLI's and
+    # its recorded origin still named the file it replaced, so `config` sent a
+    # reader to a file holding the old value.
+    merged = config.with_overrides(overrides)
+    merged_as_dict = merged.as_dict()
+    return Config(merged_as_dict, _provenance_naming_the_cli(config, merged_as_dict, frozenset(overridden)))
 
 
 __all__ = [
+    "CLI_LAYER",
     "CoercedValue",
     "ConfigOverride",
     "apply_overrides",

{bitranox_template_py_cli-1.7.1 → bitranox_template_py_cli-1.7.2}/tests/test_config_overrides.py

@@ -325,3 +325,35 @@ def test_apply_overrides_rejects_malformed_input() -> None:
 
     with pytest.raises(ValueError, match="must contain '='"):
         apply_overrides(config, ("invalid",))
+
+
+@pytest.mark.os_agnostic
+def test_apply_overrides_names_the_cli_as_the_source_of_an_overridden_key() -> None:
+    """An overridden key reports the CLI as its origin, not the layer it replaced.
+
+    ``Config.with_overrides`` returns the merged data with the ORIGINAL provenance
+    map by design, so without a rebuild ``config`` answers "where did this come
+    from" with the file holding the value that was just replaced.
+    """
+    config = Config({"s": {"k": 1}}, {"s.k": {"layer": "file", "path": "/etc/app.toml", "key": "s.k"}})
+
+    result = apply_overrides(config, ("s.k=2",))
+
+    assert result["s"]["k"] == 2
+    assert result.origin("s.k") == {"layer": "cli", "path": None, "key": "s.k"}
+
+
+@pytest.mark.os_agnostic
+def test_apply_overrides_leaves_an_untouched_key_with_its_own_source() -> None:
+    """Only the keys ``--set`` supplied are relabelled; the rest keep their layer."""
+    config = Config(
+        {"s": {"k": 1, "other": "kept"}},
+        {
+            "s.k": {"layer": "file", "path": "/etc/app.toml", "key": "s.k"},
+            "s.other": {"layer": "env", "path": None, "key": "s.other"},
+        },
+    )
+
+    result = apply_overrides(config, ("s.k=2",))
+
+    assert result.origin("s.other") == {"layer": "env", "path": None, "key": "s.other"}

{bitranox_template_py_cli-1.7.1 → bitranox_template_py_cli-1.7.2}/tests/test_safe_console.py

@@ -81,6 +81,30 @@ class TestEchoOnAUtf8Console:
         assert "✓" in buffer.getvalue().decode("utf-8")
 
 
+class TestTheDefaultTargetFollowsTheStreamEchoWritesTo:
+    """With no `file`, the encoding must come from the stream `echo` lands on.
+
+    click resolves that target itself from ``sys.stdout``/``sys.stderr``. Judge
+    the wrong stream and a legacy-codepage console gets exactly the crash this
+    module exists to prevent, while every test passing an explicit `file` stays
+    green and says nothing about it.
+    """
+
+    def test_a_cp1252_stdout_degrades_the_glyph(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        stream = _cp1252_stream()
+        monkeypatch.setattr(sys, "stdout", stream)
+        safe_console.echo("✓ deployed")
+        assert "[OK]" in _read_back(stream)
+
+    def test_err_is_judged_against_stderr_not_stdout(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """A stdout that could take the glyph must not excuse a cp1252 stderr."""
+        stream = _cp1252_stream()
+        monkeypatch.setattr(sys, "stdout", io.TextIOWrapper(io.BytesIO(), encoding="utf-8", newline=""))
+        monkeypatch.setattr(sys, "stderr", stream)
+        safe_console.echo("✓ deployed", err=True)
+        assert "[OK]" in _read_back(stream)
+
+
 class TestSafeStreamProtectsRich:
     """Rich raises on a legacy codepage too; it renders through its own writer."""