Shell Completion

The shellcompletion command is a Django management command that installs and removes shellcompletion scripts for supported shells (bash, fish, zsh, powershell). This command is also the entry point for running the completion logic and can be used to debug completer code.

shellcompletion Usage: manage.py shellcompletion [OPTIONS] COMMAND [ARGS]... Install autocompletion for the current shell. ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--shellSHELLThe shell to use.[default: sh]│ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Django ─────────────────────────────────────────────────────────────────────╮ │--no-colorFilter terminal formatting control sequences out │ │of completion text.                              │ │--force-colorAllow terminal formatting control sequences in   │ │completion text.                                 │ │--settingsTEXTThe Python path to a settings module, e.g.       │ │"myproject.settings.main". If this isn't         │ │provided, the DJANGO_SETTINGS_MODULE environment │ │variable will be used.                           │ │--pythonpathPATHA directory to add to the Python path, e.g.      │ │"/home/djangoprojects/myproject".                │ │--tracebackRaise on CommandError exceptions│ │--show-localsPrint local variables in tracebacks.│ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Commands ───────────────────────────────────────────────────────────────────╮ │install   Install autocompletion for the current or given shell.          │ │uninstall Uninstall autocompletion for the current or given shell.        │ │complete  Generate autocompletion for command string.                     │ ╰──────────────────────────────────────────────────────────────────────────────╯

install() invokes typer’s shell completion installation logic, but does have to patch the installed scripts. This is because there is only one installation for all Django management commands, not each individual command. The completion logic here will failover to Django’s builtin autocomplete if the command in question is not a TyperCommand. To promote compatibility with other management command libraries or custom completion logic, a fallback completion function can also be specified.

class django_typer.management.commands.shellcompletion.Command(stdout=None, stderr=None, no_color=False, force_color=False, **kwargs)[source]

This command installs autocompletion for the current shell. This command uses the typer/click autocompletion scripts to generate the autocompletion items, but monkey patches the scripts to invoke our bundled shell complete script which fails over to the django autocomplete function when the command being completed is not a TyperCommand. When the django autocomplete function is used we also wrap it so that it works for any supported click/typer shell, not just bash.

We also provide a remove command to easily remove the installed script.

Great pains are taken to use the upstream dependency’s shell completion logic. This is so advances and additional shell support implemented upstream should just work. However, it would be possible to add support for new shells here using the pluggable logic that click provides. It is probably a better idea however to add support for new shells at the typer level.

Shell autocompletion can be brittle with every shell having its own quirks and nuances. We make a good faith effort here to support all the shells that typer/click support, but there can easily be system specific configuration issues that prevent this from working. In those cases users should refer to the online documentation for their specific shell to troubleshoot.

Parameters:

  • stdout (OutputWrapper)

  • stderr (OutputWrapper)

  • no_color (bool)

  • force_color (bool)

  • kwargs (Any)

complete(command='', cursor=None, fallback=None)[source]

We implement the shell complete generation script as a Django command because the Django environment needs to be bootstrapped for it to work. This also allows us to test completion logic in a platform agnostic way.

Tip

This command is super useful for debugging shell_complete logic. For example to enter into the debugger, we could set a breakpoint in our shell_complete function for the option parameter and then run the following command:

$ ./manage.py shellcompletion complete "./manage.py your_command --option "
 shellcompletion Usage: shellcompletion [OPTIONS] [COMMAND] [CURSOR] Generate autocompletion for command string. ╭─ Arguments ──────────────────────────────────────────────────────────────────╮ │command[COMMAND]The command string to generate completion         │ │suggestions for.                                  │ │cursor [CURSOR]The cursor position.[default: None]│ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--fallbackTEXTThe python import path to a fallback complete       │ │function to use when the completion command is not a│ │TyperCommand. By default, the builtin django        │ │autocomplete function is used.                      │ │[default: None]                                     │ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────╯
Parameters:

  • command (Annotated[str, <typer.models.ArgumentInfo object at 0x71f32d2db440>])

  • cursor (Annotated[int | None, <typer.models.ArgumentInfo object at 0x71f32d2dbce0>])

  • fallback (Annotated[str | None, <typer.models.OptionInfo object at 0x71f32d2dbf80>])

install(manage_script=None, fallback=None, template=None, prompt=True)[source]

Install autocompletion for the given shell. If the shell is not specified, it will try to detect the shell. If the shell is not detected, it will fail.

We run the upstream typer installation routines, with some augmentation.

shellcompletion install Usage: shellcompletion install [OPTIONS] Install autocompletion for the current or given shell. ╭─ Options ─────────────────────────────────────────────────────────────────────────╮ │--manage-scriptTEXTThe name of the django manage script to install     │ │autocompletion for if different than the script used│ │to invoke this command.                             │ │[default: None]                                     │ │--fallbackTEXTThe python import path to a fallback complete       │ │function to use when the completion command is not a│ │TyperCommand.                                       │ │[default: None]                                     │ │--templateTEXTThe name of the template to use for the shell       │ │completion script.                                  │ │[default: None]                                     │ │--no-promptDo not ask for conformation before editing dotfiles.│ │[default: True]                                     │ │--helpShow this message and exit.│ ╰───────────────────────────────────────────────────────────────────────────────────╯

Returns the list of edited and/or created paths or None if no edits were made.

Parameters:

  • manage_script (Annotated[str | None, <typer.models.OptionInfo object at 0x71f32d2d93d0>])

  • fallback (Annotated[str | None, <typer.models.OptionInfo object at 0x71f32d2d9910>])

  • template (Annotated[str | None, <typer.models.OptionInfo object at 0x71f32d2d9dc0>])

  • prompt (Annotated[bool, <typer.models.OptionInfo object at 0x71f32d2da330>])

Return type:

List[Path] | None

property manage_script: str | Path

Returns the name of the manage command as a string if it is available as a command on the user path. If it is a script that is not available as a command on the path it will return an absolute Path object to the script.

property manage_script_name: str

Get the name of the manage script as a command available from the shell’s path.

property shell: str

Get the active shell. If not explicitly set, it first tries to find the shell in the environment variable shell complete scripts set and failing that it will try to autodetect the shell.

uninstall(manage_script=None)[source]

Remove the autocompletion for the given shell. If the shell is not specified, it will try to detect the shell. If the shell is not detected, it will fail.

Since the installation routine is upstream we first run install to determine where the completion script is installed and then we remove it.

 shellcompletion Usage: shellcompletion [OPTIONS] Uninstall autocompletion for the current or given shell. ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--manage-scriptTEXTThe name of the django manage script to remove │ │shell completion for if different than the     │ │script used to invoke this command.            │ │[default: None]                                │ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────╯
Parameters:

manage_script (Annotated[str | None, <typer.models.OptionInfo object at 0x71f32d2db020>])