fix: Undocumented completions.

Author: DanCardin

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ## Unreleased: 0.29.0
 
+- fix: Undocumented completions.
 - docs: Add argument validation documentation.
 - feat: Test against python 3.14.
 - fix: Apply pyright strict typing.

src/cappa/completion/base.py

@@ -69,5 +69,5 @@ def format_completions(*completions: Completion | FileCompletion) -> str | None:
     result: list[str] = []
     for item in completions:
         item = cast(Completion, item)
-        result.append(f"{item.value}:{item.help if item.help else ''}")
+        result.append(f"{item.value}:{item.description}")
     return "\n".join(result)

src/cappa/completion/types.py

@@ -29,6 +29,14 @@ def backend_template(self, prog: str, arg: Arg[Any]) -> str:
 class Completion:
     value: str | None = None
     help: str | None = None
+    arg: Arg[Any] | None = None
+
+    @property
+    def description(self) -> str:
+        if not self.arg or self.arg.help:
+            return self.help or ""
+
+        return f"<{self.arg.value_name}> {self.help}".strip()
 
 
 @dataclasses.dataclass

src/cappa/help.py

@@ -23,9 +23,6 @@
 if typing.TYPE_CHECKING:
     from cappa.command import Command
 
-HelpFormattable: TypeAlias = typing.Callable[
-    ["Command[typing.Any]", str], typing.List[Displayable]
-]
 ArgGroup: TypeAlias = typing.Tuple[
     typing.Tuple[str, bool], typing.List[typing.Union[Arg[Any], Subcommand]]
 ]
@@ -44,6 +41,16 @@
 ]
 
 
+class HelpFormattable(typing.Protocol):
+    left_padding: Dimension
+    arg_format: ArgFormat
+    default_format: str
+
+    def __call__(
+        self, command: Command[Any], prog: str
+    ) -> list[Displayable]: ...  # pragma: no cover
+
+
 def create_version_arg(version: str | Arg[Any] | None = None) -> Arg[Any] | None:
     if not version:
         return None
@@ -108,7 +115,7 @@ def create_completion_arg(completion: bool | Arg[bool] = True) -> Arg[bool] | No
 
 
 @dataclass(frozen=True)
-class HelpFormatter:
+class HelpFormatter(HelpFormattable):
     left_padding: Dimension = (0, 0, 0, 2)
     arg_format: ArgFormat = (
         Markdown("{help}"),
@@ -117,7 +124,7 @@ class HelpFormatter:
     )
     default_format: str = "(Default: {default})"
 
-    default: typing.ClassVar[Self]
+    default: typing.ClassVar[HelpFormatter]
 
     def __call__(self, command: Command[Any], prog: str) -> list[Displayable]:
         arg_groups = generate_arg_groups(command)
@@ -176,7 +183,7 @@ def add_long_args(
 
 
 def format_arg(
-    console: Console, help_formatter: HelpFormatter, arg: Arg[Any]
+    console: Console, help_formatter: HelpFormattable, arg: Arg[Any]
 ) -> Displayable:
     arg_format = help_formatter.arg_format
     if not isinstance(arg_format, Iterable) or isinstance(arg_format, str):
@@ -259,10 +266,7 @@ def _replace_rich_text_component(c: TextComponent, text: str) -> TextComponent:
             style=c.style,
             justify=c.justify,
             overflow=c.overflow,
-            # no_wrap=c.no_wrap,
             end=c.end,
-            # tab_size=c.tab_size,
-            # spans=c.spans,
         )
 
     if isinstance(c, Markdown):

src/cappa/parser.py

@@ -8,7 +8,7 @@
 from cappa.arg import Arg, ArgAction, ArgActionType, Group
 from cappa.command import Command, Subcommand
 from cappa.completion.types import Completion, FileCompletion
-from cappa.help import format_subcommand_names
+from cappa.help import format_arg, format_subcommand_names
 from cappa.invoke import fulfill_deps
 from cappa.output import Exit, HelpExit, Output
 from cappa.typing import T, assert_type
@@ -372,20 +372,30 @@ def parse_option(
     parse_state: ParseState, context: ParseContext, raw: RawOption
 ) -> None:
     if raw.name not in context.options:
-        possible_values = [
-            name for name in context.options if name.startswith(raw.name)
-        ]
+        possible_options: dict[str, Arg[Any]] = {
+            name: arg
+            for name, arg in context.options.items()
+            if name.startswith(raw.name)
+        }
 
         if parse_state.provide_completions:
-            options = [
-                Completion(option, help=context.options[option].help)
-                for option in possible_values
-            ]
+            options: list[Completion] = []
+            for name, option in possible_options.items():
+                rendered_help = str(
+                    format_arg(
+                        parse_state.output.output_console,
+                        context.command.help_formatter,
+                        option,
+                    )
+                ).strip()
+                completion = Completion(name, help=rendered_help, arg=option)
+                options.append(completion)
+
             raise CompletionAction(*options)
 
         message = f"Unrecognized arguments: {raw.name}"
-        if possible_values:
-            message += f" (Did you mean: {', '.join(possible_values)})"
+        if possible_options:
+            message += f" (Did you mean: {', '.join(possible_options.keys())})"
 
         raise BadArgumentError(
             message, value=raw.name, command=parse_state.current_command

tests/completion/test_option.py

@@ -14,7 +14,7 @@ class Args:
         default: bool = False
 
     result = parse_completion(Args, "--d")
-    assert result == "--default:"
+    assert result == "--default:<default> (Default: False)"
 
 
 def test_long_option_name_with_help():
@@ -23,7 +23,7 @@ class Args:
         default: Annotated[bool, cappa.Arg(help="Enables default")] = False
 
     result = parse_completion(Args, "--d")
-    assert result == "--default:Enables default"
+    assert result == "--default:Enables default (Default: False)"
 
 
 def test_multiple_matches():
@@ -44,3 +44,12 @@ class Args:
 
     result = parse_completion(Args, "-a")
     assert result is None
+
+
+def test_no_help_value_name():
+    @dataclass
+    class Args:
+        apple: Annotated[str, cappa.Arg(long=True)]
+
+    result = parse_completion(Args, "--a")
+    assert result == "--apple:<apple>"

tests/completion/test_subcommand.py

@@ -37,4 +37,4 @@ def test_subcommand_name_with_partial():
 def test_subcommand_args():
     result = parse_completion(Args, "bar", "--n")
     assert result
-    assert result == "--nested-opt:"
+    assert result == "--nested-opt:<nested_opt>"