Shell completion

Generate a completion script, or compute the candidates directly. See the Shell completion guide.

generate_completion

generate_completion(
    doc: str, prog: str, shell: str = "bash"
) -> str

Return a context-aware shell completion script for the CLI described by doc.

The script is a thin callback carrying no grammar of its own. At each Tab it re-invokes the program with a completion request in the environment, and that program's docopt call resolves the tokens legal at the cursor from the usage grammar. Suggestions therefore narrow to the matched subcommand's options and arguments, rather than a flat global list.

A docopt program answers those requests by default. A program that does not want this passes docopt(..., complete=False) to opt out.

Parameters:

Name	Type	Description	Default
doc	str	The usage message (the same string given to docopt).	required
prog	str	The command name the script completes for. Must be a plain command name (letters, digits, ., _, -), and must be on PATH under that name.	required
shell	str	One of "bash", "zsh", "fish", "powershell" or "nushell".	'bash'

Returns:

Type	Description
str	The completion script as text. It depends only on prog and shell, never on the usage,
str	since the grammar stays in the program.

Raises:

Type	Description
ValueError	shell is not supported, or prog is not a plain command name.
DocoptLanguageError	The usage message is malformed. It fails here rather than at Tab time.

Source code in src/docopt2/_completion.py

def generate_completion(doc: str, prog: str, shell: str = "bash") -> str:
    """Return a context-aware shell completion script for the CLI described by ``doc``.

    The script is a thin callback carrying no grammar of its own. At each Tab it re-invokes the program with
    a completion request in the environment, and that program's [`docopt`][docopt2.docopt] call resolves the
    tokens legal at the cursor from the usage grammar. Suggestions therefore narrow to the matched subcommand's options
    and arguments, rather than a flat global list.

    A docopt program answers those requests by default. A program that does not want this passes
    ``docopt(..., complete=False)`` to opt out.

    Args:
        doc: The usage message (the same string given to [`docopt`][docopt2.docopt]).
        prog: The command name the script completes for. Must be a plain command name
            (letters, digits, ``.``, ``_``, ``-``), and must be on ``PATH`` under that name.
        shell: One of ``"bash"``, ``"zsh"``, ``"fish"``, ``"powershell"`` or ``"nushell"``.

    Returns:
        The completion script as text. It depends only on ``prog`` and ``shell``, never on the usage,
        since the grammar stays in the program.

    Raises:
        ValueError: ``shell`` is not supported, or ``prog`` is not a plain command name.
        DocoptLanguageError: The usage message is malformed. It fails here rather than at Tab time.
    """
    if shell not in _RENDERERS:
        supported = ", ".join(sorted(_RENDERERS))
        raise ValueError(f"unsupported shell: {shell!r}; expected one of {supported}")
    # The script interpolates `prog` into shell/PowerShell source that is sourced or eval'd, so a
    # name with metacharacters (`;`, `$()`, spaces, quotes) would inject or corrupt it. Require a
    # plain command name.
    if not re.fullmatch(r"[A-Za-z0-9._-]+", prog):
        raise ValueError(f"prog {prog!r} must be a plain command name (letters, digits, . _ -)")
    # Validate the docstring up front so a malformed usage fails loudly here, not silently at Tab.
    single_usage_section(doc)
    return _RENDERERS[shell](prog, _function_name(prog))

complete

complete(doc: str, words: Sequence[str]) -> list[str]

Return the completion candidates for the last (cursor) word of words.

Earlier tokens are consumed against the usage pattern. The command literals and option names (never positional values) that could legally come next are returned, filtered to the partial word. A malformed doc or a prefix ending mid-option-argument yields no candidates, never raises.

Source code in src/docopt2/_completion.py

def complete(doc: str, words: Sequence[str]) -> list[str]:
    """Return the completion candidates for the last (cursor) word of ``words``.

    Earlier tokens are consumed against the usage pattern. The command literals and option names
    (never positional values) that could legally come next are returned, filtered to the partial
    word. A malformed doc or a prefix ending mid-option-argument yields no candidates, never raises.
    """
    tokens = list(words)
    incomplete = tokens[-1] if tokens else ""
    typed = tokens[:-1]
    try:
        candidates = _resolve(doc, typed)
    except (DocoptLanguageError, DocoptExit, RecursionError):
        # a malformed doc, a prefix ending mid-option-argument, or a pathologically deep pattern:
        # complete nothing rather than raising into the shell
        return []
    return [name for name in candidates if name.startswith(incomplete)]