Add new "auto_default_argument", "handle_tracebacks" and "traceback_handler" functions.

Author: domdfcoding

consolekit/options.py

@@ -80,6 +80,7 @@
 		"MultiValueOption",
 		"flag_option",
 		"auto_default_option",
+		"auto_default_argument",
 		]
 
 _A = TypeVar("_A", bound=click.Argument)
@@ -163,6 +164,8 @@ def force_option(help_text: str) -> Callable[..., click.Command]:
 	"""
 	Decorator to add the ``-f / --force`` option to a click command.
 
+	The value is exposed via the parameter ``force``: :class:`bool`.
+
 	.. versionadded:: 0.5.0
 
 	:param help_text: The help text for the option.
@@ -229,12 +232,44 @@ def decorator(f: _C) -> _C:
 		option = OptionClass(param_decls, **option_attrs)
 		_param_memo(f, option)
 
-		signature: inspect.Signature = inspect.signature(f.callback)
+		_get_default_from_callback_and_set(f, option)
+
+		return f
+
+	return decorator
 
-		param_default = signature.parameters[option.name].default
+
+def _get_default_from_callback_and_set(command: click.Command, param: click.Parameter):
+	if command.callback is not None:
+		# The callback *can* be None, for a no-op
+		signature: inspect.Signature = inspect.signature(command.callback)
+
+		param_default = signature.parameters[param.name].default
 
 		if param_default is not inspect.Signature.empty:
-			option.default = param_default
+			param.default = param_default
+
+
+def auto_default_argument(*param_decls, **attrs) -> Callable[..., click.Argument]:
+	"""
+	Attaches an argument to the command, with a default value determined from the decorated function's signature.
+
+	All positional arguments are passed as parameter declarations to :class:`click.Argument`;
+	all keyword arguments are forwarded unchanged (except ``cls``).
+	This is equivalent to creating an :class:`click.Argument` instance manually
+	and attaching it to the :attr:`click.Argument.params` list.
+
+	.. versionadded:: 0.8.0
+
+	:param cls: the option class to instantiate. This defaults to :class:`click.Argument`.
+	"""
+
+	def decorator(f: _C) -> _C:
+		ArgumentClass = attrs.pop("cls", Argument)
+		argument = ArgumentClass(param_decls, **attrs)
+		_param_memo(f, argument)
+
+		_get_default_from_callback_and_set(f, argument)
 
 		return f
 

consolekit/utils.py

@@ -54,6 +54,9 @@
 		"braille_spinner",
 		"hide_cursor",
 		"show_cursor",
+		"handle_tracebacks",
+		"traceback_handler",
+		"TerminalRenderer",
 		]
 
 
@@ -244,6 +247,70 @@ def show_cursor() -> None:
 	click.echo(Cursor.SHOW)
 
 
+nullcontext: Callable[..., ContextManager]
+
+if sys.version_info < (3, 7):  # pragma: no cover (py37+)
+
+	@contextlib.contextmanager
+	def nullcontext():
+		yield
+else:  # pragma: no cover (<py37)
+	nullcontext = contextlib.nullcontext
+
+
+@contextlib.contextmanager
+def traceback_handler():
+	"""
+	Context manager to abort execution with a short error message on the following exception types:
+
+	* :exc:`FileNotFoundError`
+	* :exc:`FileExistsError`
+
+	Other custom exception classes inheriting from :exc:`Exception` are also handled,
+	but with a generic message.
+
+	The following exception classes are ignored:
+
+	* :exc:`EOFError`
+	* :exc:`KeyboardInterrupt`
+	* :exc:`click.exceptions.ClickException`
+
+	.. versionadded:: 0.8.0
+
+	.. seealso:: :func:`~.handle_tracebacks`.
+	"""  # noqa: D400
+
+	try:
+		yield
+	except (EOFError, KeyboardInterrupt, click.ClickException, click.Abort):
+		raise
+	except FileNotFoundError as e:
+		raise abort(f"File Not Found: {e}")
+	except FileExistsError as e:
+		raise abort(f"File Exists: {e}")
+	except Exception as e:
+		raise abort(f"An error occurred: {e}")
+
+
+def handle_tracebacks(show_traceback: bool = False) -> ContextManager:
+	"""
+	Context manager to conditionally handle tracebacks, usually based on the value of a command line flag.
+
+	.. versionadded:: 0.8.0
+
+	:param show_traceback: If :py:obj:`True`, the full Python traceback will be shown on errors.
+		If :py:obj:`False`, only the summary of the traceback will be shown.
+		In either case the program execution will stop on error.
+
+	.. seealso:: :func:`~.traceback_handler`.
+	"""
+
+	if show_traceback:
+		return nullcontext()
+	else:
+		return traceback_handler()
+
+
 @lru_cache(1)
 def _pycharm_hosted():
 	return os.environ.get("PYCHARM_HOSTED", 0)

tests/test_options_/test_auto_default_option.md

@@ -0,0 +1,5 @@
+Usage: main [OPTIONS]
+
+Options:
+  --width INTEGER  The max width to display.  [default: 80]
+  -h, --help       Show this message and exit.

tests/test_utils.py

@@ -1,13 +1,20 @@
 # stdlib
+import math
+import re
 import sys
+from typing import Callable, ContextManager
 
 # 3rd party
+import click
+import pytest
+from click.testing import CliRunner, Result
 from domdf_python_tools.paths import PathPlus
 from domdf_python_tools.testing import check_file_regression
 from pytest_regressions.file_regression import FileRegressionFixture
 
 # this package
-from consolekit.utils import coloured_diff, overtype
+from consolekit import click_command
+from consolekit.utils import coloured_diff, handle_tracebacks, is_command, overtype, traceback_handler
 
 
 def test_overtype(capsys):
@@ -60,3 +67,122 @@ def test_coloured_diff(file_regression: FileRegressionFixture):
 			)
 
 	check_file_regression(diff, file_regression)
+
+
+exceptions = pytest.mark.parametrize(
+		"exception",
+		[
+				pytest.param(FileNotFoundError("foo.txt"), id="FileNotFoundError"),
+				pytest.param(FileExistsError("foo.txt"), id="FileExistsError"),
+				pytest.param(Exception("Something's awry!"), id="Exception"),
+				pytest.param(ValueError("'age' must be >= 0"), id="ValueError"),
+				pytest.param(TypeError("Expected type int, got type str"), id="TypeError"),
+				pytest.param(NameError("name 'hello' is not defined"), id="NameError"),
+				pytest.param(SyntaxError("invalid syntax"), id="SyntaxError"),
+				]
+		)
+contextmanagers = pytest.mark.parametrize(
+		"contextmanager",
+		[
+				pytest.param(handle_tracebacks, id="handle_tracebacks"),
+				pytest.param(traceback_handler, id="traceback_handler"),
+				]
+		)
+
+
+@exceptions
+@contextmanagers
+def test_handle_tracebacks(exception, contextmanager: Callable[..., ContextManager], file_regression):
+
+	@click.command()
+	def demo():
+
+		with contextmanager():
+			raise exception
+
+	runner = CliRunner()
+
+	result: Result = runner.invoke(demo, catch_exceptions=False)
+
+	check_file_regression(result.stdout.rstrip(), file_regression)
+
+	assert result.exit_code == 1
+
+
+@exceptions
+def test_handle_tracebacks_show_traceback(exception, file_regression):
+
+	@click.command()
+	def demo():
+
+		with handle_tracebacks(show_traceback=True):
+			raise exception
+
+	runner = CliRunner()
+
+	with pytest.raises(type(exception), match=re.escape(str(exception))):
+		runner.invoke(demo, catch_exceptions=False)
+
+
+@pytest.mark.parametrize("exception", [EOFError(), KeyboardInterrupt(), click.Abort()])
+@contextmanagers
+def test_handle_tracebacks_ignored_exceptions(
+		exception, contextmanager: Callable[..., ContextManager], file_regression
+		):
+
+	@click.command()
+	def demo():
+
+		with contextmanager():
+			raise exception
+
+	runner = CliRunner()
+
+	result: Result = runner.invoke(demo, catch_exceptions=False)
+
+	assert result.stdout.strip() == "Aborted!"
+	assert result.exit_code == 1
+
+
+@pytest.mark.parametrize(
+		"exception, code",
+		[
+				pytest.param(click.UsageError("Message"), 2, id="click.UsageError"),
+				pytest.param(click.BadParameter("Message"), 2, id="click.BadParameter"),
+				pytest.param(click.FileError("Message"), 1, id="click.FileError"),
+				pytest.param(click.ClickException("Message"), 1, id="click.ClickException"),
+				]
+		)
+@contextmanagers
+def test_handle_tracebacks_ignored_click(
+		exception,
+		contextmanager: Callable[..., ContextManager],
+		file_regression,
+		code: int,
+		):
+
+	@click.command()
+	def demo():
+
+		with contextmanager():
+			raise exception
+
+	runner = CliRunner()
+
+	result: Result = runner.invoke(demo, catch_exceptions=False)
+
+	check_file_regression(result.stdout.rstrip(), file_regression)
+
+	assert result.exit_code == code
+
+
+def test_is_command():
+
+	@click_command()
+	def main():
+		...
+
+	assert is_command(main)
+	assert not is_command(int)
+	assert not is_command(lambda: True)
+	assert not is_command(math.ceil)

tests/test_utils_/test_handle_tracebacks_handle_tracebacks_Exception_.txt

@@ -0,0 +1,2 @@
+An error occurred: Something's awry!
+Aborted!

tests/test_utils_/test_handle_tracebacks_handle_tracebacks_FileExistsError_.txt

@@ -0,0 +1,2 @@
+File Exists: foo.txt
+Aborted!

tests/test_utils_/test_handle_tracebacks_handle_tracebacks_FileNotFoundError_.txt

@@ -0,0 +1,2 @@
+File Not Found: foo.txt
+Aborted!

tests/test_utils_/test_handle_tracebacks_handle_tracebacks_NameError_.txt

@@ -0,0 +1,2 @@
+An error occurred: name 'hello' is not defined
+Aborted!

tests/test_utils_/test_handle_tracebacks_handle_tracebacks_SyntaxError_.txt

@@ -0,0 +1,2 @@
+An error occurred: invalid syntax
+Aborted!

tests/test_utils_/test_handle_tracebacks_handle_tracebacks_TypeError_.txt

@@ -0,0 +1,2 @@
+An error occurred: Expected type int, got type str
+Aborted!