Add subclass of click.Argument with an additional argument for storing a short description.

Author: domdfcoding

consolekit/options.py

@@ -80,6 +80,7 @@
 		"flag_option",
 		"auto_default_option",
 		"auto_default_argument",
+		"DescribedArgument",
 		"_A",
 		"_C",
 		]
@@ -119,12 +120,12 @@ def verbose_option(help_text: str = "Show verbose output.") -> Callable[[_C], _C
 	"""
 
 	return click.option(  # type: ignore
-			"-v",
-			"--verbose",
-			count=True,
-			help=help_text,
-			type=VerboseVersionCountType(),
-			)
+		"-v",
+		"--verbose",
+		count=True,
+		help=help_text,
+		type=VerboseVersionCountType(),
+		)
 
 
 def version_option(callback: Callable[[click.Context, click.Option, int], Any]) -> Callable[[_C], _C]:
@@ -156,14 +157,14 @@ def version_callback(ctx: click.Context, param: click.Option, value: int):
 	"""
 
 	return click.option(  # type: ignore
-			"--version",
-			count=True,
-			expose_value=False,
-			is_eager=True,
-			help="Show the version and exit.",
-			type=VerboseVersionCountType(),
-			callback=cast(Callback, callback),
-			)
+		"--version",
+		count=True,
+		expose_value=False,
+		is_eager=True,
+		help="Show the version and exit.",
+		type=VerboseVersionCountType(),
+		callback=cast(Callback, callback),
+		)
 
 
 def colour_option(help_text="Whether to use coloured output.") -> Callable[[_C], _C]:
@@ -468,3 +469,30 @@ def prompt_for_value(self, ctx):
 				confirmation_prompt=self.confirmation_prompt,
 				value_proc=lambda x: self.process_value(ctx, x),
 				)
+
+
+class DescribedArgument(click.Argument):
+	r"""
+	:class:`click.Argument` with an additional keyword argument and attribute giving a short description.
+
+	This is not shown in the help text,
+	but may be useful for manpages or HTML documentation where additional information can be provided.
+
+	.. versionadded:: 1.2.0
+
+	:param description:
+
+	See :class:`click.Argument` and :class:`click.Parameter` for descriptions of the other keyword argu
+	ments.
+
+	.. attribute:: description
+
+		**Type:** |nbsp| |nbsp| |nbsp| |nbsp| :py:obj:`~typing.Optional`\[:py:class:`str`\]
+
+		A short description of the argument.
+	"""
+
+	def __init__(self, *args, description: Optional[str] = None, **kwargs):
+		super().__init__(*args, **kwargs)
+
+		self.description: Optional[str] = description

tests/test_options.py

@@ -9,6 +9,7 @@
 # this package
 from consolekit import click_command
 from consolekit.options import (
+		DescribedArgument,
 		MultiValueOption,
 		auto_default_argument,
 		auto_default_option,
@@ -23,6 +24,35 @@
 from consolekit.testing import CliRunner, Result
 
 
+def test_described_argument(
+		file_regression: FileRegressionFixture,
+		cli_runner: CliRunner,
+		):
+
+	@click.argument(
+			"dest",
+			cls=DescribedArgument,
+			type=click.STRING,
+			description="The destination directory.",
+			)
+	@click_command()
+	def main(dest: str):
+		print(dest)
+
+	result = cli_runner.invoke(main, args="--help")
+	result.check_stdout(file_regression, extension=".md")
+	assert result.exit_code == 0
+
+	result = cli_runner.invoke(main, catch_exceptions=False, args="./staging")
+	assert result.stdout.rstrip() == "./staging"
+	assert result.exit_code == 0
+
+	ctx = click.Context(main, info_name="main", parent=None)
+	argument = ctx.command.params[0]
+	assert isinstance(argument, DescribedArgument)
+	assert argument.description == "The destination directory."
+
+
 def test_auto_default_option(
 		file_regression: FileRegressionFixture,
 		cli_runner: CliRunner,

tests/test_options_/test_described_argument.md

@@ -0,0 +1,4 @@
+Usage: main [OPTIONS] DEST
+
+Options:
+  -h, --help  Show this message and exit.