lib-cli-exit-tools 2.3.3__tar.gz → 2.3.4__tar.gz

{lib_cli_exit_tools-2.3.3 → lib_cli_exit_tools-2.3.4}/CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to this project are documented here. The format follows [Kee
 
 ## [Unreleased]
 
+## [2.3.4] 2026-07-29 15:20:59
+
+### Fixed
+- `run_cli()` now returns the exit code a command chose with `ctx.exit(...)` instead of always reporting `0` on the non-exception path. Click is invoked with `standalone_mode=False`, which makes it *return* that code rather than raising it, and `_run_command_with_handler` discarded the value before returning a hardcoded `0`. Only the exception path could therefore produce a non-zero status, so a command that completed normally while reporting a negative *answer* - a host that did not respond, a search that found nothing, anything distinguishing "ran fine, result is no" from "failed" - silently exited `0`. `ClickCommand.main` is annotated `-> object` to match what Click actually returns. A command that simply completes still yields `0`, since Click returns `None` there.
+
+  No released behaviour changes for existing users: a sweep of every project in this tree found no other consumer calling `ctx.exit()` with a non-zero code, no test pinned the previous behaviour, and the documented `run_cli` contract in the README already described executing the command with `standalone_mode=False` without mentioning that its result was dropped.
+
 ## [2.3.3] 2026-07-24 16:09:16
 
 ### Fixed

{lib_cli_exit_tools-2.3.3 → lib_cli_exit_tools-2.3.4}/Makefile

@@ -1,4 +1,4 @@
-# BMK MAKEFILE 3.13.0
+# BMK MAKEFILE 3.13.2
 # 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,7 +186,7 @@ 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.13.0
+BMK_MIN := 3.13.2
 
 # 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.

{lib_cli_exit_tools-2.3.3 → lib_cli_exit_tools-2.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lib_cli_exit_tools
-Version: 2.3.3
+Version: 2.3.4
 Summary: CLI exit handling helpers: clean signals, exit codes, and error printing
 Project-URL: Homepage, https://github.com/bitranox/lib_cli_exit_tools
 Project-URL: Repository, https://github.com/bitranox/lib_cli_exit_tools.git
@@ -27,7 +27,7 @@ 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: coverage[toml]>=7.15.2; extra == 'dev'
-Requires-Dist: hypothesis>=6.161.2; extra == 'dev'
+Requires-Dist: hypothesis>=6.163.0; extra == 'dev'
 Requires-Dist: import-linter>=2.13; extra == 'dev'
 Requires-Dist: pip-audit>=2.10.1; extra == 'dev'
 Requires-Dist: pyright[nodejs]>=1.1.411; extra == 'dev'
@@ -37,7 +37,7 @@ Requires-Dist: pytest>=9.1.1; extra == 'dev'
 Requires-Dist: rtoml>=0.13.0; extra == 'dev'
 Requires-Dist: ruff>=0.16.0; extra == 'dev'
 Requires-Dist: textual>=8.2.8; extra == 'dev'
-Requires-Dist: twine>=6.2.0; extra == 'dev'
+Requires-Dist: twine>=7.0.0; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # lib_cli_exit_tools

{lib_cli_exit_tools-2.3.3 → lib_cli_exit_tools-2.3.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "lib_cli_exit_tools"
-version = "2.3.3"
+version = "2.3.4"
 description = "CLI exit handling helpers: clean signals, exit codes, and error printing"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -51,7 +51,7 @@ dev = [
   # Transitive CVE pins
   "click>=8.4.2",                # CVE-2026-7246
   "coverage[toml]>=7.15.2",
-  "hypothesis>=6.161.2",
+  "hypothesis>=6.163.0",
   "import-linter>=2.13",
   "bandit>=1.9.4",
   "pip-audit>=2.10.1",
@@ -62,7 +62,7 @@ dev = [
   "ruff>=0.16.0",
   "textual>=8.2.8",
   "rtoml>=0.13.0",
-  "twine>=6.2.0"
+  "twine>=7.0.0"
 ]
 
 [project.scripts]

{lib_cli_exit_tools-2.3.3 → lib_cli_exit_tools-2.3.4}/src/lib_cli_exit_tools/__init__conf__.py

@@ -26,7 +26,7 @@ name = "lib_cli_exit_tools"
 #: Human-readable summary shown in CLI help output.
 title = "CLI exit handling helpers: clean signals, exit codes, and error printing"
 #: Current release version pulled from ``pyproject.toml`` by automation.
-version = "2.3.3"
+version = "2.3.4"
 #: Repository homepage presented to users.
 homepage = "https://github.com/bitranox/lib_cli_exit_tools"
 #: Author attribution surfaced in CLI output.

{lib_cli_exit_tools-2.3.3 → lib_cli_exit_tools-2.3.4}/src/lib_cli_exit_tools/application/runner.py

@@ -60,7 +60,9 @@ class ClickCommand(Protocol):
         complete_var: str | None = ...,
         standalone_mode: bool = ...,  # noqa: FBT001 - mirrors Click's actual positional main() signature
         **_: object,
-    ) -> None: ...
+    ) -> object:
+        """Return Click's own result: ctx.exit()'s code, or None on success."""
+        ...
 
 
 __all__ = [
@@ -681,10 +683,15 @@ def _run_command_with_handler(
 ) -> int:
     """Invoke the Click command and delegate failures to ``handler``."""
     try:
-        _invoke_command(cli, argv, prog_name)
+        outcome = _invoke_command(cli, argv, prog_name)
     except BaseException as exc:  # single funnel for exit codes; handler translates every exception type
         return handler(exc)
-    return 0
+    # Click is invoked with standalone_mode=False, which makes it *return*
+    # ctx.exit()'s code rather than raising it. That is how a command reports a
+    # negative answer - nothing found, host did not respond - as distinct from
+    # an error. Discarding this value would collapse every such outcome to
+    # success; None is Click's plain-success result and stays 0.
+    return outcome if isinstance(outcome, int) else 0
 
 
 def _finalise_cli_run(restorer: Callable[[], None] | None) -> None:
@@ -693,9 +700,15 @@ def _finalise_cli_run(restorer: Callable[[], None] | None) -> None:
     flush_streams()
 
 
-def _invoke_command(cli: ClickCommand, argv: Sequence[str] | None, prog_name: str | None) -> None:
-    """Invoke the Click command with ``standalone_mode`` disabled."""
-    cli.main(args=_normalised_args(argv), standalone_mode=False, prog_name=prog_name)
+def _invoke_command(cli: ClickCommand, argv: Sequence[str] | None, prog_name: str | None) -> object:
+    """Invoke the Click command with ``standalone_mode`` disabled.
+
+    Returns:
+        Whatever Click returns: the code passed to ``ctx.exit()``, or ``None``
+        when the command simply completed.
+    """
+
+    return cli.main(args=_normalised_args(argv), standalone_mode=False, prog_name=prog_name)
 
 
 def _normalised_args(argv: Sequence[str] | None) -> Sequence[str] | None:

{lib_cli_exit_tools-2.3.3 → lib_cli_exit_tools-2.3.4}/tests/test_application_runner.py

@@ -476,3 +476,96 @@ def test_run_cli_skips_signal_installation_when_disabled(monkeypatch: pytest.Mon
     runner.run_cli(DummyCommand(lambda: None), install_signals=False)
 
     assert called == []
+
+
+# =============================================================================
+# Exit codes a command chose deliberately
+# =============================================================================
+
+
+def _no_signal_handlers(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Keep these tests from touching process-wide signal state."""
+
+    def install(_specs: Sequence[SignalSpec]) -> Callable[[], None]:
+        def restore() -> None:
+            return None
+
+        return restore
+
+    monkeypatch.setattr(runner, "install_signal_handlers", install)
+
+
+def _command_exiting_with(code: int) -> click.Command:
+    """Return a real Click command that deliberately exits with ``code``.
+
+    A real command rather than the stub above, because the stub cannot
+    reproduce Click's return-value behaviour and that is exactly what is
+    under test here.
+    """
+
+    @click.pass_context
+    def body(ctx: click.Context) -> None:
+        ctx.exit(code)
+
+    return click.command()(body)
+
+
+def _group_with_subcommand_exiting_with(code: int) -> click.Group:
+    """Return a group whose subcommand exits with ``code``."""
+
+    @click.group()
+    def app() -> None: ...
+
+    @click.pass_context
+    def body(ctx: click.Context) -> None:
+        ctx.exit(code)
+
+    app.add_command(click.command("check")(body))
+    return app
+
+
+@pytest.mark.os_agnostic
+def test_run_cli_propagates_a_deliberate_non_zero_exit(monkeypatch: pytest.MonkeyPatch) -> None:
+    """A command that calls ctx.exit(1) must exit 1, not 0.
+
+    ``ctx.exit`` is how a Click command reports a negative *answer* - a host
+    that did not respond, a search that found nothing - as distinct from an
+    error. With ``standalone_mode=False`` Click returns that code rather than
+    raising it, so it only reaches the caller if the return value is passed on.
+    Dropping it collapses every such outcome into success.
+    """
+
+    _no_signal_handlers(monkeypatch)
+
+    assert runner.run_cli(_command_exiting_with(1), [], prog_name="t") == 1
+
+
+@pytest.mark.os_agnostic
+@pytest.mark.parametrize("code", [1, 2, 3, 42])
+def test_run_cli_propagates_every_deliberate_exit_code(monkeypatch: pytest.MonkeyPatch, code: int) -> None:
+    """Whatever code the command chose is the code the caller receives."""
+
+    _no_signal_handlers(monkeypatch)
+
+    assert runner.run_cli(_command_exiting_with(code), [], prog_name="t") == code
+
+
+@pytest.mark.os_agnostic
+def test_run_cli_still_returns_zero_for_a_command_that_just_returns(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Click returns None on a plain success, which must still mean zero."""
+
+    _no_signal_handlers(monkeypatch)
+
+    def body() -> None:
+        click.echo("done")
+
+    assert runner.run_cli(click.command()(body), [], prog_name="t") == 0
+
+
+@pytest.mark.os_agnostic
+def test_run_cli_propagates_a_deliberate_exit_from_a_subcommand(monkeypatch: pytest.MonkeyPatch) -> None:
+    """The same holds one level down, which is where real CLIs exit from."""
+
+    _no_signal_handlers(monkeypatch)
+
+    assert runner.run_cli(_group_with_subcommand_exiting_with(1), ["check"], prog_name="t") == 1