Completion

Note

This feature is only supported when using the cappa.backend.

Completion support is enabled by default. You can disable completion by sending completion=False into your parse or invoke call.

By default, this adds a --completion [generate/complete] argument to the resultant CLI. You can customize the name/visibility/help/etc of that argument by supplying an Arg to the same argument (completion=Arg(...)).

Enabling Completions

Note

Currently supported shells for completions include:

  • Zsh

  • Bash

  • Fish

Submissions for additional shell support is very welcome.

--completion generate outputs $SHELL-specific source to power the completions for the CLI A user of your CLI needs to redirect to the appropriate default location for completions for that shell.

Alternatively they can write it to an arbitrary location and source the resultant file in their shell-rc file, although this is not recommended!

mycli --completion generate > ~/.mycli.sh

Completable Values

Currently cappa supports completions for

  • --option long/short names

  • Subcommand names

  • Argument values

    By default this does local file completion for most argument types.

    If the argument defines logical “choices” (Enum, Union of Literals), those choices will be completed instead.

Custom Completions

Any Arg can supply a completion=function argument to produce arbitrary completions for that field. function (in this case) should be a function which accepts a string (the partial string to complete), and returns a list of Completion

import cappa

def names(partial: str) -> cappa.Completion:
    names = ['Lucy', 'Bob', 'Ron']
    return [
        cappa.Completion(name, help='Available Names')
        for name in names
        if name.startswith(partial)
    ]

cappa.Arg(..., completion=names)