strictcli 0.35.3__tar.gz → 0.35.4__tar.gz

{strictcli-0.35.3 → strictcli-0.35.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: strictcli
-Version: 0.35.3
+Version: 0.35.4
 Summary: A strict CLI framework for Python
 Project-URL: Homepage, https://github.com/smm-h/strictcli
 Project-URL: Repository, https://github.com/smm-h/strictcli

{strictcli-0.35.3 → strictcli-0.35.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "strictcli"
-version = "0.35.3"
+version = "0.35.4"
 description = "A strict CLI framework for Python"
 readme = "README.md"
 license = "MIT"

{strictcli-0.35.3 → strictcli-0.35.4}/strictcli/__init__.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-__version__ = "0.35.3"
+__version__ = "0.35.4"
 
 __all__ = [
     "App", "Flag", "Arg", "FlagSet", "MutexGroup", "CoRequired", "Requires",
@@ -674,6 +674,16 @@ def _msg_dry_run_truncated(step: int, cmd: str, brand: str) -> str:
     )
 
 
+def _msg_dry_run_aborted(step: int, cmd: str) -> str:
+    """The aborted-preview marker. Same shape and prefix as the truncation
+    error above: both say the preview ended before the handler finished, and
+    they differ only in why and in what the reader may conclude."""
+    return (
+        f"error: dry-run preview ends at step {step}: {cmd} aborted — "
+        f"the preview above may be incomplete"
+    )
+
+
 def _msg_confirm_prompt(cmd_path: str) -> str:
     """The confirm prompt. A prompt, not an error, but parity is still checked."""
     return f"about to run mutating command '{cmd_path}'. Proceed? [y/N] "
@@ -5508,6 +5518,29 @@ class App:
         """Start a new dispatch: reset the structured effect log."""
         self._effect_log = _EffectLog()
 
+    def _render_dry_log(self, cmd_path: str, *, aborted: bool) -> None:
+        """Write the would-do log for a dry run. No-op outside dry mode.
+
+        Called on every exit path out of a dispatch, so a handler that leaves
+        through ``sys.exit`` or an exception still shows the preview it was
+        asked for. The log always goes to stdout and is never suppressed by
+        ``--quiet``: it is dry mode's primary output.
+
+        ``aborted`` marks a dispatch that did not finish. The log is still
+        written -- the recorded effects are owed either way -- and the marker
+        that follows it on stderr says the reader cannot assume the list is
+        the whole preview. The truncation path (which ends the preview for its
+        own pinned reason) renders itself and never comes through here.
+        """
+        if not self._last_dry_run:
+            return
+        print(self._effect_log.render())
+        if aborted:
+            print(
+                _msg_dry_run_aborted(self._effect_log.next_seq(), cmd_path),
+                file=sys.stderr,
+            )
+
     def _record_cache_write(self, path: str) -> None:
         """Record a framework-blessed CACHE_WRITE.
 
@@ -6873,20 +6906,31 @@ class App:
             )
             # The confirm protocol fires only on the real CLI path.
             self._confirm_mutating(cmd, cmd_path)
+            # The would-do log renders on EVERY exit path out of the dispatch,
+            # not just the normal return: the operator asked for a preview and
+            # the effects were recorded, so a handler that unwinds through
+            # sys.exit or an exception still owes them the list. The clause set
+            # below is exhaustive by construction -- BaseException is the root
+            # of the hierarchy, so no unwind can slip past it.
             try:
                 if cmd.passthrough is not None:
                     result = cmd.passthrough.handler(ctx, cmd.name, data, self._last_global_values)
                 else:
                     result = cmd.handler(ctx, **data)
+                exit_code, out_data = _interpret_handler_return(result)
+                if out_data is not _MISSING:
+                    print(json.dumps(out_data, default=str, separators=(",", ":")))
             except _DryRunTruncated as trunc:
                 print(trunc.log.render())
                 print(trunc.message, file=sys.stderr)
                 sys.exit(1)
-            exit_code, out_data = _interpret_handler_return(result)
-            if out_data is not _MISSING:
-                print(json.dumps(out_data, default=str, separators=(",", ":")))
-            if self._last_dry_run:
-                print(self._effect_log.render())
+            except SystemExit:
+                self._render_dry_log(cmd_path, aborted=False)
+                raise
+            except BaseException:
+                self._render_dry_log(cmd_path, aborted=True)
+                raise
+            self._render_dry_log(cmd_path, aborted=False)
             sys.exit(exit_code)
 
     def test(self, argv: list[str]) -> Result:
@@ -6945,9 +6989,9 @@ class App:
             exit_code = 1
         else:
             self._begin_dispatch()
+            cmd_path = ".".join(self._last_resolved_path + [cmd.name])
             # Record test-coverage hit (command-level only).
             if self.test_coverage:
-                cmd_path = ".".join(self._last_resolved_path + [cmd.name])
                 self._record_coverage(cmd_path)
             # Store sources for function handlers that need provenance info
             self._last_sources = sources
@@ -6959,9 +7003,7 @@ class App:
                         dry_run=self._last_dry_run, yes=self._last_yes,
                         quiet=self._last_quiet, verbose=self._last_verbose,
                         effects=self._arm_effects(
-                            cmd,
-                            ".".join(self._last_resolved_path + [cmd.name]),
-                            dry_run=self._last_dry_run,
+                            cmd, cmd_path, dry_run=self._last_dry_run,
                         ),
                     )
                     if cmd.passthrough is not None:
@@ -6974,14 +7016,17 @@ class App:
                     if out_data is not _MISSING:
                         result_data = out_data
                         print(json.dumps(out_data, default=str, separators=(",", ":")))
-                    if self._last_dry_run:
-                        print(self._effect_log.render())
+                    self._render_dry_log(cmd_path, aborted=False)
                 except _DryRunTruncated as trunc:
                     print(trunc.log.render())
                     print(trunc.message, file=sys.stderr)
                     exit_code = 1
                 except SystemExit as e:
                     exit_code = e.code if isinstance(e.code, int) else (1 if e.code else 0)
+                    self._render_dry_log(cmd_path, aborted=False)
+                except BaseException:
+                    self._render_dry_log(cmd_path, aborted=True)
+                    raise
 
         return Result(
             stdout=stdout_buf.getvalue(),

{strictcli-0.35.3 → strictcli-0.35.4}/tests/test_effects.py

@@ -203,6 +203,187 @@ class TestWouldDoLog:
         assert (tmp_path / "build").is_dir()
 
 
+_EXPECTED_LOG = (
+    "DRY RUN — no changes were made. Would do:\n"
+    "  1. write: report.txt (2 bytes)\n"
+)
+
+
+class TestWouldDoLogOnEveryExitPath:
+    """The log renders on every exit path out of a dispatch, not just the
+    normal return: `sys.exit`, an uncaught exception, and a bad handler
+    return all still show the preview the operator asked for."""
+
+    @staticmethod
+    def _app_with(handler_tail):
+        app = _app()
+
+        @app.command("rel", help="rel", effect="mutating")
+        def _rel(ctx):
+            ctx.effects.write("report.txt", "ok")
+            return handler_tail()
+
+        return app
+
+    def test_sys_exit_still_renders_the_log(self):
+        app = self._app_with(lambda: sys.exit(1))
+        r = app.test(["--dry-run", "rel"])
+        assert r.exit_code == 1
+        assert r.stdout == _EXPECTED_LOG
+        assert r.stderr == ""
+
+    def test_sys_exit_renders_the_same_bytes_as_an_equivalent_return(self):
+        """`sys.exit(1)` and `return 1` are the same intent; the preview must
+        not depend on which spelling the handler chose."""
+        exiting = self._app_with(lambda: sys.exit(1)).test(["--dry-run", "rel"])
+        returning = self._app_with(lambda: 1).test(["--dry-run", "rel"])
+        assert exiting.stdout == returning.stdout
+        assert exiting.stderr == returning.stderr
+        assert exiting.exit_code == returning.exit_code
+
+    def test_sys_exit_with_no_code_renders_the_log(self):
+        app = self._app_with(lambda: sys.exit())
+        r = app.test(["--dry-run", "rel"])
+        assert r.exit_code == 0
+        assert r.stdout == _EXPECTED_LOG
+
+    def test_sys_exit_renders_nothing_outside_dry_mode(self, tmp_path, monkeypatch):
+        monkeypatch.chdir(tmp_path)
+        app = self._app_with(lambda: sys.exit(1))
+        r = app.test(["rel"])
+        assert r.exit_code == 1
+        assert "DRY RUN" not in r.stdout
+
+    def test_sys_exit_renders_the_log_on_the_run_path(self, monkeypatch, capsys):
+        app = self._app_with(lambda: sys.exit(1))
+        monkeypatch.setattr(sys, "argv", ["app", "--dry-run", "rel"])
+        with pytest.raises(SystemExit) as exc:
+            app.run()
+        assert exc.value.code == 1
+        captured = capsys.readouterr()
+        assert captured.out == _EXPECTED_LOG
+        assert captured.err == ""
+
+    def test_uncaught_exception_renders_the_log_marked_incomplete(
+        self, monkeypatch, capsys
+    ):
+        def _boom():
+            raise RuntimeError("kaboom")
+
+        app = self._app_with(_boom)
+        monkeypatch.setattr(sys, "argv", ["app", "--dry-run", "rel"])
+        with pytest.raises(RuntimeError, match="kaboom"):
+            app.run()
+        captured = capsys.readouterr()
+        assert captured.out == _EXPECTED_LOG
+        assert captured.err == (
+            "error: dry-run preview ends at step 2: rel aborted — "
+            "the preview above may be incomplete\n"
+        )
+
+    def test_an_aborted_preview_names_the_dotted_command_path(
+        self, monkeypatch, capsys
+    ):
+        app = _app()
+        grp = app.group("release", help="release")
+
+        @grp.command("run", help="run", effect="mutating")
+        def _run(ctx):
+            raise RuntimeError("kaboom")
+
+        monkeypatch.setattr(sys, "argv", ["app", "--dry-run", "release", "run"])
+        with pytest.raises(RuntimeError):
+            app.run()
+        captured = capsys.readouterr()
+        assert captured.out == "DRY RUN — no changes were made. Would do:\n"
+        assert "release.run aborted" in captured.err
+
+    def test_uncaught_exception_renders_nothing_outside_dry_mode(
+        self, monkeypatch, capsys, tmp_path
+    ):
+        monkeypatch.chdir(tmp_path)
+
+        def _boom():
+            raise RuntimeError("kaboom")
+
+        app = self._app_with(_boom)
+        monkeypatch.setattr(sys, "argv", ["app", "--yes", "rel"])
+        with pytest.raises(RuntimeError):
+            app.run()
+        captured = capsys.readouterr()
+        assert "DRY RUN" not in captured.out
+        assert "aborted" not in captured.err
+
+    def test_bad_handler_return_renders_the_log_marked_incomplete(
+        self, monkeypatch, capsys
+    ):
+        app = self._app_with(lambda: ["not", "an", "outcome"])
+        monkeypatch.setattr(sys, "argv", ["app", "--dry-run", "rel"])
+        with pytest.raises(TypeError, match="command handler must return"):
+            app.run()
+        captured = capsys.readouterr()
+        assert captured.out == _EXPECTED_LOG
+        assert "rel aborted" in captured.err
+
+    def test_the_abort_marker_never_reaches_stdout(self, monkeypatch, capsys):
+        """§3.4: the log is stdout's; the marker that qualifies it is stderr's,
+        exactly like the truncation error."""
+
+        def _boom():
+            raise RuntimeError("kaboom")
+
+        app = self._app_with(_boom)
+        monkeypatch.setattr(sys, "argv", ["app", "--quiet", "--dry-run", "rel"])
+        with pytest.raises(RuntimeError):
+            app.run()
+        captured = capsys.readouterr()
+        assert "aborted" not in captured.out
+        assert captured.out == _EXPECTED_LOG
+
+    def test_a_read_only_abort_still_renders_header_with_empty_body(
+        self, monkeypatch, capsys
+    ):
+        app = _app()
+
+        @app.command("look", help="look", effect="read_only")
+        def _look(ctx):
+            raise RuntimeError("kaboom")
+
+        monkeypatch.setattr(sys, "argv", ["app", "--dry-run", "look"])
+        with pytest.raises(RuntimeError):
+            app.run()
+        captured = capsys.readouterr()
+        assert captured.out == "DRY RUN — no changes were made. Would do:\n"
+        assert "look aborted" in captured.err
+
+    def test_truncation_still_owns_its_own_rendering(self, monkeypatch, capsys):
+        """The truncation path renders itself and exits 1; the abort marker
+        must not double up on it."""
+        app = _app()
+
+        @app.command("rel", help="rel", effect="mutating")
+        def _rel(ctx):
+            u = ctx.effects.run(["git", "status"])
+            if u:
+                pass
+            return 0
+
+        monkeypatch.setattr(sys, "argv", ["app", "--dry-run", "rel"])
+        with pytest.raises(SystemExit) as exc:
+            app.run()
+        assert exc.value.code == 1
+        captured = capsys.readouterr()
+        assert captured.out == (
+            "DRY RUN — no changes were made. Would do:\n"
+            "  1. run: git status\n"
+        )
+        assert captured.err == (
+            "error: dry-run preview ends at step 2: rel branched on unsettled "
+            "value «step 1 output» — cannot preview past this point\n"
+        )
+        assert "aborted" not in captured.err
+
+
 class TestTruncation:
     def test_branching_on_a_carrier_truncates(self):
         app = _app()

{strictcli-0.35.3 → strictcli-0.35.4}/uv.lock

@@ -232,7 +232,7 @@ wheels = [
 
 [[package]]
 name = "strictcli"
-version = "0.35.3"
+version = "0.35.4"
 source = { editable = "." }
 dependencies = [
     { name = "tomlkit" },