feat: add failure_message option for tasks (#2080)

* If a `failure_message` option is provided, show that message:
  "Task N failed: a nice failure message"
* If no `failure_message` option is provided, show the subprocess exception:
  "Task N failed: Command 'might-fail' returned non-zero exit status 1."

Addresses Issue #2080: #2080

Author: dusktreader

copier/errors.py

@@ -145,25 +145,31 @@ def __init__(
         returncode: int,
         stdout: str | bytes | None,
         stderr: str | bytes | None,
+        message: str | None = None,
     ):
         subprocess.CalledProcessError.__init__(
             self, returncode=returncode, cmd=command, output=stdout, stderr=stderr
         )
-        UserMessageError.__init__(
-            self,
-            message=f"Task {command!r} returned non-zero exit status {returncode}.",
-        )
+        if not message:
+            message = subprocess.CalledProcessError.__str__(self)
+        UserMessageError.__init__(self, message=message)
+
+    def __str__(self) -> str:
+        return self.message
 
     @classmethod
     def from_process(
-        cls, process: CompletedProcess[str] | CompletedProcess[bytes]
+        cls,
+        process: CompletedProcess[str] | CompletedProcess[bytes],
+        message: str | None = None,
     ) -> Self:
         """Create a TaskError from a CompletedProcess."""
         return cls(
             command=process.args,
             returncode=process.returncode,
             stdout=process.stdout,
             stderr=process.stderr,
+            message=message,
         )
 
 

copier/main.py

@@ -391,7 +391,14 @@ def _execute_tasks(self, tasks: Sequence[Task]) -> None:
             with local.cwd(working_directory), local.env(**extra_env):
                 process = subprocess.run(task_cmd, shell=use_shell, env=local.env)
                 if process.returncode:
-                    raise TaskError.from_process(process)
+                    if task.failure_message:
+                        message = self._render_string(task.failure_message, extra_context)
+                    else:
+                        message = f"{task_cmd!r} returned non-zero exit status {process.returncode}"
+                    raise TaskError.from_process(
+                        process,
+                        message=f"Task {i + 1} failed: {message}.",
+                    )
 
     def _render_context(self) -> AnyByStrMutableMapping:
         """Produce render context for Jinja."""

copier/template.py

@@ -168,12 +168,17 @@ class Task:
         working_directory:
             The directory from inside where to execute the task.
             If `None`, the project directory will be used.
+
+        failure_message:
+            If provided, show the message when a task fails.
+            If not provided, show the exception message from `subprocess`.
     """
 
     cmd: str | Sequence[str]
     extra_vars: dict[str, Any] = field(default_factory=dict)
     condition: str | bool = True
     working_directory: Path = Path()
+    failure_message: str | None = None
 
 
 @dataclass
@@ -525,6 +530,7 @@ def tasks(self) -> Sequence[Task]:
                         extra_vars=extra_vars,
                         condition=task.get("when", "true"),
                         working_directory=Path(task.get("working_directory", ".")),
+                        failure_message=task.get("failure_message"),
                     )
                 )
             else:

docs/configuring.md

@@ -1572,6 +1572,8 @@ If a `dict` is given it can contain the following items:
 -   **when** (optional): Specifies a condition that needs to hold for the task to run.
 -   **working_directory** (optional): Specifies the directory in which the command will
     be run. Defaults to the destination directory.
+-   **failure_message** (optional): Provides a message to print if the task fails. If
+    not provided, the subprocess exception message will be shown.
 
 If a `str` or `List[str]` is given as a task it will be treated as `command` with all
 other items not present.
@@ -1599,6 +1601,8 @@ Refer to the example provided below for more information.
           when: "{{ _copier_conf.os in  ['linux', 'macos'] }}"
         - command: Remove-Item {{ name_of_the_project }}\\README.md
           when: "{{ _copier_conf.os == 'windows' }}"
+        - command: finalize-project
+          failure_message: Coudln't finalize {{ name_of_the_project }}
     ```
 
     Note: the example assumes you use [Invoke](https://www.pyinvoke.org/) as

tests/test_tasks.py

@@ -3,6 +3,7 @@
 from pathlib import Path
 from typing import Literal
 
+from copier.errors import TaskError
 import pytest
 import yaml
 
@@ -123,7 +124,7 @@ def test_pretend_mode(tmp_path_factory: pytest.TempPathFactory) -> None:
     copier.run_copy(str(src), dst, pretend=True, unsafe=True)
     assert not (dst / "created-by-task.txt").exists()
 
-
+Literal["linux", "macos", "windows"]
 @pytest.mark.parametrize(
     "os, filename",
     [
@@ -180,3 +181,38 @@ def test_copier_phase_variable(tmp_path_factory: pytest.TempPathFactory) -> None
     )
     copier.run_copy(str(src), dst, unsafe=True)
     assert (dst / "tasks").exists()
+
+
+@pytest.mark.parametrize(
+    "task,failure_message,match,data",
+    [
+        ("false", "Oh, dear! The task failed", r"Task \d+ failed: Oh, dear! The task failed\.", None),
+        ("ls non-existing-directory", None, r"Task \d+ failed: 'ls non-existing-directory' returned non-zero exit status 2\.", None),
+        ("false", "{{ name }} blew up", r"Task \d+ failed: Wile E. Coyote blew up\.", {"name": "Wile E. Coyote"}),
+    ],
+)
+def test_task_failure_message(
+    tmp_path_factory: pytest.TempPathFactory,
+    task: str,
+    failure_message: str | None,
+    match: str,
+    data: dict[str, str] | None,
+) -> None:
+    src, dst = map(tmp_path_factory.mktemp, ("src", "dst"))
+    yaml_dict = {
+        "_tasks": [
+            {
+                "command": task,
+            }
+        ]
+    }
+    if failure_message:
+        yaml_dict["_tasks"][0]["failure_message"] = failure_message
+
+    build_file_tree(
+        {
+            (src / "copier.yml"): yaml.safe_dump(yaml_dict)
+        }
+    )
+    with pytest.raises(TaskError, match=match):
+        copier.run_copy(str(src), dst, unsafe=True, data=data)