Make _Option public as PromptOption and add ChoiceOption counterpart.

Author: domdfcoding

consolekit/__init__.py

@@ -50,7 +50,7 @@
 # this package
 from consolekit import _readline, commands, input, terminal_colours, tracebacks, utils  # noqa: F401
 from consolekit.commands import SuggestionGroup
-from consolekit.options import _Option
+from consolekit.options import PromptOption
 
 # pylint: enable=redefined-builtin
 
@@ -132,7 +132,7 @@ def option(
 	:param \*\*attrs: Additional keyword arguments passed to :func:`click.command`.
 	"""
 
-	attrs.setdefault("cls", _Option)
+	attrs.setdefault("cls", PromptOption)
 	return cast(Callable[[_C], _C], click.option(*param_decls, **attrs))
 
 

consolekit/__init__.pyi

@@ -13,7 +13,6 @@ from consolekit import terminal_colours as terminal_colours  # noqa: F401
 from consolekit import tracebacks as tracebacks  # noqa: F401
 from consolekit import utils as utils  # noqa: F401
 from consolekit.commands import SuggestionGroup as SuggestionGroup  # noqa: F401
-from consolekit.options import _Option  # noqa: F401
 
 __author__: str
 __copyright__: str

consolekit/options.py

@@ -60,7 +60,7 @@
 
 # stdlib
 import inspect
-from typing import Any, Callable, Iterable, List, Optional, Tuple, TypeVar, cast
+from typing import Any, Callable, Iterable, List, Optional, Sequence, Tuple, TypeVar, Union, cast
 
 # 3rd party
 import click
@@ -77,9 +77,12 @@
 		"colour_option",
 		"force_option",
 		"no_pager_option",
+		"PromptOption",
+		"ChoiceOption",
 		"MultiValueOption",
 		"flag_option",
 		"auto_default_option",
+		"VerboseVersionCountType",
 		"auto_default_argument",
 		"DescribedArgument",
 		"_A",
@@ -457,13 +460,20 @@ def get_default(self, ctx):  # noqa: MAN001,MAN002,D102
 			return ret
 
 
-class _Option(click.Option):
+class PromptOption(click.Option):
+	"""
+	:class:`click.Option` subclass that prompts for a value if none is provided on the command line.
+
+	Supports boolean, string or numeric values.
 
-	def prompt_for_value(self, ctx: click.Context):  # noqa: MAN002,PRM002
+	.. versionadded:: 1.11.0
+	"""
+
+	def prompt_for_value(self, ctx: click.Context):  # noqa: MAN002
 		"""
-		This is an alternative flow that can be activated in the full value processing if a value does not exist.
+		Prompt the user until a valid value exists and then returns the processed value as result.
 
-		It will prompt the user until a valid value exists and then returns the processed value as result.
+		:param ctx:
 		"""
 
 		# Calculate the default before prompting anything to be stable.
@@ -489,6 +499,72 @@ def prompt_for_value(self, ctx: click.Context):  # noqa: MAN002,PRM002
 				)
 
 
+class ChoiceOption(click.Option):  # noqa: PRM002
+	"""
+	:class:`click.Option` subclass for a string choice.
+
+	If a value is not provided a prompt (where the user chooses the corresponding number) is shown.
+
+	:param param_decls: The parameter declarations for this option.
+	:param type: The type that should be used.
+	:param show_default: Show the default value for this option in its help text.
+		Values are not shown by default, unless :attr:`Context.show_default` is :py:obj:`True`.
+		If this value is a string, it shows that string in parentheses instead of the actual value.
+		This is particularly useful for dynamic options.
+		For single option boolean flags, the default remains hidden if its value is :py:obj:`False`.
+	:param prompt: The prompt text. Defaults to the option name (capitalised and with spaces) if unset.
+	:param help: The help text.
+	:param hidden: Hide this option from help outputs.
+	:param show_choices:
+	:param deprecated: If :py:obj:`True` or a non-empty string, issues a message indicating that the argument is deprecated
+		and highlights its deprecation in --help.
+		The message can be customized by using a string as the value.
+		A deprecated parameter cannot be required, a ValueError will be raised otherwise.
+
+	.. versionadded:: 1.11.0
+	"""
+
+	# TODO: type: click.Choice[str]
+	type: click.Choice
+	prompt: str
+
+	def __init__(
+			self,
+			param_decls: Sequence[str],
+			# TODO: type: click.Choice[str],  # noqa: A002  # pylint: disable=redefined-builtin
+			type: click.Choice,  # noqa: A002  # pylint: disable=redefined-builtin
+			show_default: Union[bool, str, None] = None,
+			prompt: str = '',
+			help: Optional[str] = None,  # noqa: A002  # pylint: disable=redefined-builtin
+			hidden: bool = False,
+			show_choices: bool = True,
+			# deprecated: Union[bool, str] = False,
+			**kwargs,
+			) -> None:
+
+		super().__init__(
+				param_decls=param_decls,
+				show_default=show_default,
+				prompt=prompt or True,
+				help=help,
+				hidden=hidden,
+				show_choices=show_choices,
+				# deprecated=deprecated,
+				type=type,
+				default=None,
+				)
+
+	def prompt_for_value(self, ctx: click.Context) -> str:
+		"""
+		Show the prompt if a value was not provided.
+
+		:param ctx:
+		"""
+
+		choices = list(self.type.choices)
+		return choices[consolekit.input.choice(choices, text=self.prompt, start_index=1)]
+
+
 class DescribedArgument(click.Argument):  # noqa: PRM002
 	r"""
 	:class:`click.Argument` with an additional keyword argument and attribute giving a short description.

tests/test_options.py

@@ -4,13 +4,17 @@
 
 # 3rd party
 import click
+import pytest
+from coincidence.regressions import AdvancedFileRegressionFixture
 from pytest_regressions.file_regression import FileRegressionFixture
 
 # this package
 from consolekit import click_command
 from consolekit.options import (
+		ChoiceOption,
 		DescribedArgument,
 		MultiValueOption,
+		PromptOption,
 		auto_default_argument,
 		auto_default_option,
 		colour_option,
@@ -21,7 +25,7 @@
 		version_option
 		)
 from consolekit.terminal_colours import ColourTrilean
-from consolekit.testing import CliRunner, Result
+from consolekit.testing import CliRunner, Result, _click_major, _click_version, click_8_only, not_click_8
 
 
 def test_described_argument(
@@ -305,3 +309,107 @@ def main(greeting: str = "Hello") -> None:
 	result = cli_runner.invoke(main, args=["Good Morning"])
 	assert result.stdout.rstrip() == "Good Morning User!"
 	assert result.exit_code == 0
+
+
+@pytest.mark.parametrize(
+		"click_version",
+		[pytest.param('7', marks=click_8_only), pytest.param('8', marks=not_click_8)],
+		)
+def test_choice_option(
+		advanced_file_regression: AdvancedFileRegressionFixture,
+		click_version: str,
+		cli_runner: CliRunner,
+		):
+
+	@click.option(
+			"-s",
+			"--station",
+			help="The station to play.",
+			type=click.Choice(["Radio 1", "Radio 2", "Radio 3"], case_sensitive=False),
+			cls=ChoiceOption,
+			prompt="Select a station",
+			)
+	@click_command()
+	def main(station: str) -> None:
+		print(f"Tuning to station: {station}")
+
+	result = cli_runner.invoke(main, input="5\n0\n2\n")
+	assert result.exit_code == 0
+	advanced_file_regression.check(result.stdout.rstrip())
+
+	result = cli_runner.invoke(main, args=["--station", "Radio 1"])
+	assert result.exit_code == 0
+	assert result.stdout.rstrip() == "Tuning to station: Radio 1"
+
+
+not_click_8_or_above_82 = pytest.mark.skipif(
+		_click_major != 8 or (_click_major == 8 and _click_version[1] >= 2), reason="Output differs on click 8"
+		)
+not_click_8_or_below_82 = pytest.mark.skipif(
+		_click_major != 8 or (_click_major == 8 and _click_version[1] < 2), reason="Output differs on click 8.2"
+		)
+
+
+@pytest.mark.parametrize(
+		"click_version",
+		[
+				pytest.param('7', marks=click_8_only),
+				pytest.param('8', marks=not_click_8_or_above_82),
+				pytest.param("8.2", marks=not_click_8_or_below_82),
+				],
+		)
+def test_prompt_option(
+		advanced_file_regression: AdvancedFileRegressionFixture,
+		click_version: str,
+		cli_runner: CliRunner,
+		):
+
+	@click.option(
+			"-s",
+			"--station",
+			help="The station to play.",
+			type=click.Choice(["Radio 1", "Radio 2", "Radio 3"], case_sensitive=False),
+			cls=PromptOption,
+			prompt="Select a station",
+			)
+	@click_command()
+	def main(station: str) -> None:
+		print(f"Tuning to station: {station}")
+
+	result = cli_runner.invoke(main, input="Radio 4\nRadio 2\n")
+	assert result.exit_code == 0
+	advanced_file_regression.check(result.stdout.rstrip())
+
+	result = cli_runner.invoke(main, args=["--station", "Radio 1"])
+	assert result.exit_code == 0
+	assert result.stdout.rstrip() == "Tuning to station: Radio 1"
+
+
+@pytest.mark.parametrize(
+		"click_version",
+		[pytest.param('7', marks=click_8_only), pytest.param('8', marks=not_click_8)],
+		)
+def test_prompt_option_flag(
+		advanced_file_regression: AdvancedFileRegressionFixture,
+		click_version: str,
+		cli_runner: CliRunner,
+		):
+
+	@flag_option(
+			"--colour/--no-colour",
+			help="Show colour in output.",
+			cls=PromptOption,
+			default=None,
+			prompt="Show colour:",
+			)
+	@click_command()
+	def main(colour: bool) -> None:
+		print(f"Show colour? {colour}")
+
+	result = cli_runner.invoke(main, input="Z\nY\n")
+	assert result.exit_code == 0
+	advanced_file_regression.check(result.stdout.rstrip())
+
+	result = cli_runner.invoke(main, args=["--no-colour"])
+	assert result.exit_code == 0
+	assert result.stdout.rstrip() == "Show colour? False"

tests/test_options_/test_choice_option_7_.txt

@@ -0,0 +1,9 @@
+ [1] Radio 1
+ [2] Radio 2
+ [3] Radio 3
+Select a station: 5
+Error: 5 is not in the valid range of 1 to 3.
+Select a station: 0
+Error: 0 is not in the valid range of 1 to 3.
+Select a station: 2
+Tuning to station: Radio 2

tests/test_options_/test_choice_option_8_.txt

@@ -0,0 +1,9 @@
+ [1] Radio 1
+ [2] Radio 2
+ [3] Radio 3
+Select a station: 5
+Error: 5 is not in the range 1<=x<=3.
+Select a station: 0
+Error: 0 is not in the range 1<=x<=3.
+Select a station: 2
+Tuning to station: Radio 2

tests/test_options_/test_prompt_option_7_.txt

@@ -0,0 +1,4 @@
+Select a station (Radio 1, Radio 2, Radio 3): Radio 4
+Error: invalid choice: Radio 4. (choose from Radio 1, Radio 2, Radio 3)
+Select a station (Radio 1, Radio 2, Radio 3): Radio 2
+Tuning to station: Radio 2

tests/test_options_/test_prompt_option_8_.txt

@@ -0,0 +1,4 @@
+Select a station (Radio 1, Radio 2, Radio 3): Radio 4
+Error: 'Radio 4' is not one of 'Radio 1', 'Radio 2', 'Radio 3'.
+Select a station (Radio 1, Radio 2, Radio 3): Radio 2
+Tuning to station: Radio 2

tests/test_options_/test_prompt_option_8_2_.txt

@@ -0,0 +1,4 @@
+Select a station (Radio 1, Radio 2, Radio 3): Radio 4
+Error: 'Radio 4' is not one of 'radio 1', 'radio 2', 'radio 3'.
+Select a station (Radio 1, Radio 2, Radio 3): Radio 2
+Tuning to station: Radio 2

tests/test_options_/test_prompt_option_flag_7_.txt

@@ -0,0 +1,4 @@
+Show colour: [y/N]: Z
+Error: invalid input
+Show colour: [y/N]: Y
+Show colour? True