✨ Add TaskError exception for subprocess management

[tsvikas]

Introduce the TaskError exception to handle subprocess failures gracefully.

solves #1990

[sisp]

Thanks for your contribution, @tsvikas! 🙏

I have two minor suggestions (see inline comment).

IIUC, a failing task will raise the TaskError exception and the message will be shown, but the error from the task command will be hidden when running Copier via CLI, as it's not printed anymore but only accessible via the stdout/stderr attributes of the exception object. I think we should catch this exception in

copier/copier/cli.py

Lines 66 to 80 in a731d2b

	def _handle_exceptions(method: Callable[[], None]) -> int:
	"""Handle keyboard interruption while running a method."""
	try:
	try:
	method()
	except KeyboardInterrupt:
	raise UserMessageError("Execution stopped by user")
	except UserMessageError as error:
	print(colors.red | "\n".join(error.args), file=sys.stderr)
	return 1
	except UnsafeTemplateError as error:
	print(colors.red | "\n".join(error.args), file=sys.stderr)
	# DOCS https://github.com/copier-org/copier/issues/1328#issuecomment-1723214165
	return 0b100
	return 0

and print the message plus stdout/stderr.

[tsvikas]

IIUC, a failing task will raise the TaskError exception and the message will be shown, but the error from the task command will be hidden when running Copier via CLI, as it's not printed anymore but only accessible via the stdout/stderr attributes of the exception object. I think we should catch this exception in

Actually, the stdout/stderr will be None, since we did not capture them in subprocess.run(), and the output of the process still goes to the screen.

So we only need to output the message itself ("Task {command!r} returned non-zero exit status {returncode}.").
I believe that inheriting from UserMessageError will take care of that nicely?

[tsvikas]

I did all of the requested changes, except inheriting from CalledProcessError (see my comment above) - waiting for more input for that.
Hopefully i didn't do too much mess in the comments/review here 🙏

[tsvikas]

Done :)

[sisp]

@tsvikas I have a few minor remarks.

@copier-org/maintainers What is the correct use of UserMessageError? When I check its occurrences, it seems this error is directly raised when it originates from an improper use of Copier that can be fixed by the user. One counter-example I've seen is a missing --unsafe/--trust flag which raises UnsafeTemplateError (which isn't a subclass of UserMessageError), although this problem can be resolved by a Copier user by adding the flag. What about a task error? Is it an error caused mainly by a template author which can't be fixed by a user? Is subclassing UserMessageError appropriate in this case? WDYT?

[sisp]

I'd prefer removing this line and reverting the typing changes accordingly, and address this change in a separate PR to avoid mixing concerns here.

[tsvikas]

@copier-org/maintainers What is the correct use of UserMessageError? When I check its occurrences, it seems this error is directly raised when it originates from an improper use of Copier that can be fixed by the user. One counter-example I've seen is a missing --unsafe/--trust flag which raises UnsafeTemplateError (which isn't a subclass of UserMessageError), although this problem can be resolved by a Copier user by adding the flag. What about a task error? Is it an error caused mainly by a template author which can't be fixed by a user? Is subclassing UserMessageError appropriate in this case? WDYT?

personally i assumed that UserMessageError is for any exception that should be reported to the user in a message.
if it is not the case, i will be happy for input about the way the @copier-org/maintainers prefer to use to report something to the user. is it the printf_exception function? something else? i don't want to add here a 2nd/3rd way to do something simple.