ixt-cli 0.8.0__py3-none-any.whl

ixt/cli/argparse_completion.py

@@ -0,0 +1,557 @@
+"""Shell completion generation from an ``argparse`` parser.
+
+The parser remains the source of truth for commands, options, and choices.
+This module extracts the small subset of argparse metadata needed to render
+shell scripts without adding a third-party dependency.
+"""
+
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass, field
+from typing import Literal
+
+SUPPORTED_COMPLETION_SHELLS = ("bash", "zsh", "fish")
+CompletionValueKind = Literal["none", "file", "dir"]
+
+
+def complete_with(action: argparse.Action, value_kind: CompletionValueKind) -> argparse.Action:
+    """Annotate an argparse action with a shell completion value kind."""
+    action.__dict__["_ixt_completion_value_kind"] = value_kind
+    return action
+
+
+@dataclass(frozen=True)
+class CompletionArgument:
+    """One positional argument exposed by an argparse command."""
+
+    name: str
+    help: str = ""
+    choices: tuple[str, ...] = ()
+    value_kind: CompletionValueKind = "none"
+
+
+@dataclass(frozen=True)
+class CompletionOption:
+    """One option exposed by an argparse command."""
+
+    flags: tuple[str, ...]
+    help: str = ""
+    choices: tuple[str, ...] = ()
+    takes_value: bool = False
+    value_kind: CompletionValueKind = "none"
+
+
+@dataclass(frozen=True)
+class CompletionCommand:
+    """A command node extracted from argparse."""
+
+    path: tuple[str, ...] = ()
+    help: str = ""
+    options: tuple[CompletionOption, ...] = ()
+    arguments: tuple[CompletionArgument, ...] = ()
+    subcommands: tuple[CompletionCommand, ...] = field(default_factory=tuple)
+
+
+@dataclass(frozen=True)
+class CompletionCandidate:
+    """One word that can be completed, optionally with a description."""
+
+    word: str
+    help: str = ""
+
+
+def render_completion(parser: argparse.ArgumentParser, shell: str) -> str:
+    """Render a completion script for *shell* from *parser*."""
+    tree = extract_completion_tree(parser)
+    if shell == "bash":
+        return _render_bash(tree)
+    if shell == "zsh":
+        return _render_zsh(tree)
+    if shell == "fish":
+        return _render_fish(tree)
+    supported = ", ".join(SUPPORTED_COMPLETION_SHELLS)
+    raise ValueError(f"unsupported completion shell: {shell} (expected one of: {supported})")
+
+
+def extract_completion_tree(parser: argparse.ArgumentParser) -> CompletionCommand:
+    """Extract command, option, and choice metadata from *parser*."""
+    return _extract_command(parser, path=(), help_text=parser.description or "")
+
+
+def _extract_command(
+    parser: argparse.ArgumentParser,
+    *,
+    path: tuple[str, ...],
+    help_text: str = "",
+) -> CompletionCommand:
+    options: list[CompletionOption] = []
+    arguments: list[CompletionArgument] = []
+    subcommands: list[CompletionCommand] = []
+
+    for action in parser._actions:
+        if _is_subparsers_action(action):
+            helps = {
+                choice.dest: choice.help or "" for choice in getattr(action, "_choices_actions", [])
+            }
+            hidden = {
+                str(choice.dest)
+                for choice in getattr(action, "_choices_actions", [])
+                if choice.help == argparse.SUPPRESS
+            }
+            choices = getattr(action, "choices", None)
+            if not isinstance(choices, dict):
+                continue
+            for name, subparser in choices.items():
+                if not isinstance(subparser, argparse.ArgumentParser):
+                    continue
+                if str(name) in hidden:
+                    continue
+                subcommands.append(
+                    _extract_command(
+                        subparser,
+                        path=(*path, str(name)),
+                        help_text=helps.get(str(name), subparser.description or ""),
+                    )
+                )
+            continue
+
+        if action.help == argparse.SUPPRESS:
+            continue
+
+        if action.option_strings:
+            options.append(
+                CompletionOption(
+                    flags=tuple(action.option_strings),
+                    help=action.help or "",
+                    choices=_choices(action),
+                    takes_value=getattr(action, "nargs", None) != 0,
+                    value_kind=_value_kind(action),
+                )
+            )
+        else:
+            arguments.append(
+                CompletionArgument(
+                    name=action.dest,
+                    help=action.help or "",
+                    choices=_choices(action),
+                    value_kind=_value_kind(action),
+                )
+            )
+
+    return CompletionCommand(
+        path=path,
+        help=help_text,
+        options=tuple(options),
+        arguments=tuple(arguments),
+        subcommands=tuple(subcommands),
+    )
+
+
+def _is_subparsers_action(action: argparse.Action) -> bool:
+    return action.__class__.__name__ == "_SubParsersAction"
+
+
+def _choices(action: argparse.Action) -> tuple[str, ...]:
+    choices = getattr(action, "choices", None)
+    if choices is None or isinstance(choices, dict):
+        return ()
+    return tuple(str(choice) for choice in choices)
+
+
+def _value_kind(action: argparse.Action) -> CompletionValueKind:
+    value = getattr(action, "_ixt_completion_value_kind", "none")
+    if value in ("none", "file", "dir"):
+        return value
+    return "none"
+
+
+def _iter_commands(command: CompletionCommand) -> list[CompletionCommand]:
+    commands = [command]
+    for child in command.subcommands:
+        commands.extend(_iter_commands(child))
+    return commands
+
+
+def _path_key(path: tuple[str, ...]) -> str:
+    return " ".join(path)
+
+
+def _command_candidates(command: CompletionCommand) -> list[str]:
+    return [candidate.word for candidate in _command_candidate_details(command)]
+
+
+def _command_candidate_details(command: CompletionCommand) -> list[CompletionCandidate]:
+    words: list[CompletionCandidate] = []
+    words.extend(CompletionCandidate(child.path[-1], child.help) for child in command.subcommands)
+    for option in command.options:
+        words.extend(CompletionCandidate(flag, option.help) for flag in option.flags)
+    return words
+
+
+def _argument_value_completion(command: CompletionCommand) -> CompletionArgument | None:
+    if command.subcommands:
+        return None
+    for argument in command.arguments:
+        if argument.choices or argument.value_kind != "none":
+            return argument
+    return None
+
+
+def _word_list(words: list[str] | tuple[str, ...]) -> str:
+    return " ".join(words)
+
+
+def _zsh_quote(value: str) -> str:
+    return (
+        '"'
+        + (value.replace("\\", "\\\\").replace('"', '\\"').replace("$", "\\$").replace("`", "\\`"))
+        + '"'
+    )
+
+
+def _zsh_candidate(value: str, help_text: str = "") -> str:
+    return _zsh_quote(f"{value}:{help_text}" if help_text else value)
+
+
+def _case_label(value: str) -> str:
+    return '"' + value.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+def _bash_value_completion_lines(
+    *,
+    value_kind: CompletionValueKind,
+    choices: tuple[str, ...] = (),
+) -> list[str]:
+    if choices:
+        return [
+            f'      COMPREPLY=( $(compgen -W "{_word_list(choices)}" -- "$cur") )',
+            "      return 0",
+        ]
+    if value_kind == "file":
+        return [
+            '      COMPREPLY=( $(compgen -f -- "$cur") )',
+            "      return 0",
+        ]
+    if value_kind == "dir":
+        return [
+            '      COMPREPLY=( $(compgen -d -- "$cur") )',
+            "      return 0",
+        ]
+    return ["      return 0"]
+
+
+def _zsh_value_completion_lines(
+    *,
+    value_kind: CompletionValueKind,
+    choices: tuple[str, ...] = (),
+) -> list[str]:
+    if choices:
+        return [
+            f"      compadd -- {_word_list(choices)}",
+            "      return",
+        ]
+    if value_kind == "file":
+        return [
+            "      _files",
+            "      return",
+        ]
+    if value_kind == "dir":
+        return [
+            "      _files -/",
+            "      return",
+        ]
+    return ["      return"]
+
+
+def _bash_path_detector(root: CompletionCommand) -> list[str]:
+    lines = [
+        '  local path=""',
+        "  local word",
+        "  local idx=1",
+        "  while [[ $idx -lt $COMP_CWORD ]]; do",
+        '    word="${COMP_WORDS[$idx]}"',
+        '    case "$path" in',
+    ]
+    for command in _iter_commands(root):
+        if not command.subcommands:
+            continue
+        key = _path_key(command.path)
+        patterns = "|".join(child.path[-1] for child in command.subcommands)
+        next_path = "$word" if not key else f"{key} $word"
+        lines.extend(
+            [
+                f"      {_case_label(key)})",
+                '        case "$word" in',
+                f'          {patterns}) path="{next_path}" ;;',
+                "        esac",
+                "        ;;",
+            ]
+        )
+    lines.extend(
+        [
+            "    esac",
+            "    ((idx++))",
+            "  done",
+        ]
+    )
+    return lines
+
+
+def _zsh_path_detector(root: CompletionCommand) -> list[str]:
+    lines = [
+        '  local path=""',
+        "  local word",
+        "  local idx=2",
+        "  while (( idx < CURRENT )); do",
+        '    word="${words[idx]}"',
+        '    case "$path" in',
+    ]
+    for command in _iter_commands(root):
+        if not command.subcommands:
+            continue
+        key = _path_key(command.path)
+        patterns = "|".join(child.path[-1] for child in command.subcommands)
+        next_path = "$word" if not key else f"{key} $word"
+        lines.extend(
+            [
+                f"      {_case_label(key)})",
+                '        case "$word" in',
+                f'          {patterns}) path="{next_path}" ;;',
+                "        esac",
+                "        ;;",
+            ]
+        )
+    lines.extend(
+        [
+            "    esac",
+            "    (( idx++ ))",
+            "  done",
+        ]
+    )
+    return lines
+
+
+def _render_bash(root: CompletionCommand) -> str:
+    lines = [
+        "# bash completion for ixt",
+        "_ixt_completion() {",
+        "  local cur prev",
+        "  COMPREPLY=()",
+        '  cur="${COMP_WORDS[COMP_CWORD]}"',
+        '  prev="${COMP_WORDS[COMP_CWORD-1]}"',
+        "",
+    ]
+    lines.extend(_bash_path_detector(root))
+    lines.extend(["", '  case "$path|$prev" in'])
+    for command in _iter_commands(root):
+        key = _path_key(command.path)
+        for option in command.options:
+            if not option.takes_value:
+                continue
+            for flag in option.flags:
+                lines.extend(
+                    [
+                        f"    {_case_label(f'{key}|{flag}')})",
+                        *_bash_value_completion_lines(
+                            choices=option.choices,
+                            value_kind=option.value_kind,
+                        ),
+                        "      ;;",
+                    ]
+                )
+    lines.extend(["  esac", "", '  case "$path" in'])
+    for command in _iter_commands(root):
+        candidates = _command_candidates(command)
+        argument = _argument_value_completion(command)
+        if not candidates and argument is None:
+            continue
+        key = _path_key(command.path)
+        words = _word_list(candidates)
+        lines.append(f"    {_case_label(key)})")
+        if words:
+            lines.append(f'      COMPREPLY=( $(compgen -W "{words}" -- "$cur") )')
+        if argument is not None:
+            if argument.choices:
+                lines.append(
+                    f'      COMPREPLY+=( $(compgen -W "{_word_list(argument.choices)}" -- "$cur") )'
+                )
+            elif argument.value_kind == "file":
+                lines.append('      COMPREPLY+=( $(compgen -f -- "$cur") )')
+            elif argument.value_kind == "dir":
+                lines.append('      COMPREPLY+=( $(compgen -d -- "$cur") )')
+        lines.append("      ;;")
+    lines.extend(
+        [
+            "  esac",
+            "  return 0",
+            "}",
+            "complete -F _ixt_completion ixt",
+            "",
+        ]
+    )
+    return "\n".join(lines)
+
+
+def _render_zsh(root: CompletionCommand) -> str:
+    lines = [
+        "#compdef ixt",
+        "",
+        "_ixt() {",
+        "  local cur prev",
+        '  cur="${words[CURRENT]}"',
+        '  prev="${words[CURRENT-1]}"',
+        "",
+    ]
+    lines.extend(_zsh_path_detector(root))
+    lines.extend(["", '  case "$path|$prev" in'])
+    for command in _iter_commands(root):
+        key = _path_key(command.path)
+        for option in command.options:
+            if not option.takes_value:
+                continue
+            for flag in option.flags:
+                lines.extend(
+                    [
+                        f"    {_case_label(f'{key}|{flag}')})",
+                        *_zsh_value_completion_lines(
+                            choices=option.choices,
+                            value_kind=option.value_kind,
+                        ),
+                        "      ;;",
+                    ]
+                )
+    lines.extend(["  esac", "", '  case "$path" in'])
+    for command in _iter_commands(root):
+        candidates = _command_candidate_details(command)
+        argument = _argument_value_completion(command)
+        if not candidates and argument is None:
+            continue
+        key = _path_key(command.path)
+        lines.append(f"    {_case_label(key)})")
+        if candidates:
+            lines.append("      local -a candidates")
+            lines.append("      candidates=(")
+            for candidate in candidates:
+                lines.append(f"        {_zsh_candidate(candidate.word, candidate.help)}")
+            lines.append("      )")
+            lines.append("      _describe 'ixt completions' candidates")
+        if argument is not None:
+            lines.extend(
+                "  " + line
+                for line in _zsh_value_completion_lines(
+                    choices=argument.choices,
+                    value_kind=argument.value_kind,
+                )
+                if "return" not in line
+            )
+        lines.append("      ;;")
+    lines.extend(
+        [
+            "  esac",
+            "}",
+            "",
+            "compdef _ixt ixt",
+            "",
+        ]
+    )
+    return "\n".join(lines)
+
+
+def _fish_quote(value: str) -> str:
+    return "'" + value.replace("\\", "\\\\").replace("'", "\\'") + "'"
+
+
+def _fish_condition_for_path(path: tuple[str, ...]) -> str:
+    if not path:
+        return ""
+    return "; and ".join(f"__fish_seen_subcommand_from {part}" for part in path)
+
+
+def _fish_condition_for_child(parent: CompletionCommand) -> str:
+    if not parent.path:
+        return "__fish_use_subcommand"
+    pieces = [_fish_condition_for_path(parent.path)]
+    if parent.subcommands:
+        siblings = " ".join(child.path[-1] for child in parent.subcommands)
+        pieces.append(f"not __fish_seen_subcommand_from {siblings}")
+    return "; and ".join(piece for piece in pieces if piece)
+
+
+def _fish_option_names(option: CompletionOption) -> list[str]:
+    parts: list[str] = []
+    long_flags = [flag for flag in option.flags if flag.startswith("--")]
+    short_flags = [
+        flag for flag in option.flags if flag.startswith("-") and not flag.startswith("--")
+    ]
+    if long_flags:
+        parts.extend(["-l", long_flags[0][2:]])
+    if short_flags:
+        parts.extend(["-s", short_flags[0][1:]])
+    return parts
+
+
+def _fish_argument_value(argument: CompletionArgument) -> str | None:
+    if argument.choices:
+        return " ".join(argument.choices)
+    if argument.value_kind == "dir":
+        return "(__fish_complete_directories)"
+    if argument.value_kind == "file":
+        return "(__fish_complete_path)"
+    return None
+
+
+def _render_fish(root: CompletionCommand) -> str:
+    lines = ["# fish completion for ixt"]
+    for command in _iter_commands(root):
+        condition = _fish_condition_for_path(command.path)
+        for option in command.options:
+            parts = ["complete", "-c", "ixt"]
+            if option.value_kind not in ("file", "dir"):
+                parts.append("-f")
+            if condition:
+                parts.extend(["-n", _fish_quote(condition)])
+            parts.extend(_fish_option_names(option))
+            if option.takes_value:
+                parts.append("-r")
+            if option.choices:
+                parts.extend(["-a", _fish_quote(" ".join(option.choices))])
+            elif option.value_kind == "dir":
+                parts.extend(["-a", _fish_quote("(__fish_complete_directories)")])
+            elif option.value_kind == "file":
+                parts.extend(["-a", _fish_quote("(__fish_complete_path)")])
+            if option.help:
+                parts.extend(["-d", _fish_quote(option.help)])
+            lines.append(" ".join(parts))
+
+        argument = _argument_value_completion(command)
+        argument_value = _fish_argument_value(argument) if argument else None
+        if argument is not None and argument_value is not None:
+            parts = ["complete", "-c", "ixt"]
+            if condition:
+                parts.extend(["-n", _fish_quote(condition)])
+            if argument.value_kind == "dir":
+                parts.append("-f")
+            parts.extend(["-a", _fish_quote(argument_value)])
+            if argument.help:
+                parts.extend(["-d", _fish_quote(argument.help)])
+            lines.append(" ".join(parts))
+
+        child_condition = _fish_condition_for_child(command)
+        for child in command.subcommands:
+            parts = [
+                "complete",
+                "-c",
+                "ixt",
+                "-f",
+                "-n",
+                _fish_quote(child_condition),
+                "-a",
+                _fish_quote(child.path[-1]),
+            ]
+            if child.help:
+                parts.extend(["-d", _fish_quote(child.help)])
+            lines.append(" ".join(parts))
+
+    lines.append("")
+    return "\n".join(lines)