Shells

class django_typer.shells.DjangoTyperShellCompleter(cli=None, ctx_args={}, prog_name='', complete_var='', command=None, command_str=None, command_args=None, template=None, color=None, color_default=True, **kwargs)

An extension to the click shell completion classes that provides a Django specific shell completion implementation. If you wish to support a new shell, you must derive from this class, implement all of the abstract methods, and register the class with register_completion_class()

Parameters:

• cli (Command | None) – The click command object to complete

• ctx_args (MutableMapping[str, Any]) – Additional context arguments to pass to the typer/click context of the management command being completed

• prog_name (str) – The name of the command to complete

• complete_var (str) – The name of the environment variable to pass the completion string (unused)

• command (ShellCompletion | None) – The Django shellcompletion command

• command_str (str | None) – The command string to complete

• command_args (List[str] | None) – The command arguments to complete

• template (str | None) – The name of the shell completion script template

• color (bool | None) – Allow or disallow color and formatting in the completion output

• color_default (bool)

__init__(cli=None, ctx_args={}, prog_name='', complete_var='', command=None, command_str=None, command_args=None, template=None, color=None, color_default=True, **kwargs)

Parameters:

• cli (Command | None)

• ctx_args (MutableMapping[str, Any])

• prog_name (str)

• complete_var (str)

• command (ShellCompletion | None)

• command_str (str | None)

• command_args (List[str] | None)

• template (str | None)

• color (bool | None)

• color_default (bool)

color: bool = False

By default, allow or disallow color and formatting in the completion output.

get_completion_args()

Return the list of completion arguments and the incomplete string.

Return type:

Tuple[List[str], str]

get_completions(args, incomplete)

Get the completions for the current command string and incomplete string.

Parameters:

• args (List[str])

• incomplete (str)

Return type:

List[CompletionItem]

abstractmethod get_user_profile()

Most shells have a profile script that is sourced when the interactive shell starts. Deriving classes should implement this method to return the location of that script.

Return type:

Path

abstractmethod install(prompt=True)

Deriving classes must implement this method to install the completion script.

This method should return the path to the installed script.

Parameters:

prompt (bool) – If True, prompt the user for confirmation before installing the completion script.

Returns:

The paths that were created or edited or None if the user declined installation or no changes were made.

Return type:

List[Path]

property is_installed: bool

Whether or not the manage script is a command on the path.

load_template()

Return a compiled Template object for the completion script template.

Return type:

Template | Template

process_rich_text(text)

Removes rich text markup from a string if color is disabled, otherwise it will render the rich markup to ansi control codes. If rich is not installed, none of this happens and the markup will be passed through as is.

Parameters:

text (str)

Return type:

str

prompt(source, file, prompt=True, start_line=0)

Prompt the user for confirmation before editing the file with the given source edits.

Parameters:

• source (str) – The source string that will be written to the file.

• file (Path) – The path of the file that will be created or edited.

• prompt (bool) – Prompt toggle, if False, will not prompt the user and return True

• start_line (int) – The line number the edit will start at.

Returns:

True if the user confirmed the edit, False otherwise.

Return type:

bool

source()

Render the completion script template to a string.

Return type:

str

property source_template: str

The contents of the shell’s completion script template.

source_vars()

This returns the context that will be used to render the completion script template.

From the base class we inherit the following variables:

• complete_func: the name to use for the shell’s completion function

• complete_var: unused because we do not use environment variables

  to pass the completion string

• prog_name: the name of the command to complete

We add the following variables:

• manage_script: the manage script object - will be either a string or a Path, if it is a Path it will be absolute and this indicates that the script is not installed on the path

• manage_script_name: the name of the Django manage script

• python: the path to the python interpreter that is running the shellcompletion command

• django_command: the name of the Django shellcompletion command - you may change this to something other than ‘shellcompletion’ to provide custom complete logic

• color: the color flag to pass to shellcompletion i.e. –(force|no)-color

• fallback: the fallback option to pass to shellcompletion complete

• is_installed: whether or not the manage script is a command on the path

• shell: the name of the shell

Return type:

Dict[str, Any]

supports_scripts: bool = False

Does the shell support completions for uninstalled scripts? (i.e. not on the path)

template: str

The name of the shell completion function script template.

abstractmethod uninstall()

Deriving classes must implement this method to uninstall the completion script.

django_typer.shells.register_completion_class(cls)

Register a shell completion class for use with the Django shellcompletion command.

Parameters:

cls (Type[DjangoTyperShellCompleter])

Return type:

None

class django_typer.shells.bash.BashComplete(cli=None, ctx_args={}, prog_name='', complete_var='', command=None, command_str=None, command_args=None, template=None, color=None, color_default=True, **kwargs)

This completer class supports the bash shell. Completion scripts are installed in the ~/.bash_completions directory and are sourced in ~/.bashrc.

Bash does not support help text in completions so these are not returned. The format of the completion is type,value and different suggestions are separated by newlines.

See also: https://github.com/scop/bash-completion#faq

Parameters:

• cli (Command | None)

• ctx_args (MutableMapping[str, Any])

• prog_name (str)

• complete_var (str)

• command (ShellCompletion | None)

• command_str (str | None)

• command_args (List[str] | None)

• template (str | None)

• color (bool | None)

• color_default (bool)

color: bool = False

Zsh does support ansi control codes in completion suggestions, but we disable them by default.

name: t.ClassVar[str] = 'bash'

shell executable.

supports_scripts: bool = True

The bash completer supports script invocations.

template: str = 'shell_complete/bash.sh'

The template used to render the bash completion script.

class django_typer.shells.zsh.ZshComplete(cli=None, ctx_args={}, prog_name='', complete_var='', command=None, command_str=None, command_args=None, template=None, color=None, color_default=True, **kwargs)

This completer class supports Zsh. Completion scripts are installed to the .zfunc directory in the user’s home directory. Style and completion initialization instructions are added to the user’s .zshrc file if needed.

Returned suggestions are delimited by newlines. Each suggestion is on three lines:

• The first line is the type of the completion.

• The second line is the value of the completion.

• The third line is the help text for the completion.

See also: https://github.com/zsh-users/zsh-completions/blob/master/zsh-completions-howto.org

Parameters:

• cli (Command | None)

• ctx_args (MutableMapping[str, Any])

• prog_name (str)

• complete_var (str)

• command (ShellCompletion | None)

• command_str (str | None)

• command_args (List[str] | None)

• template (str | None)

• color (bool | None)

• color_default (bool)

color: bool = False

Zsh does support ansi control codes in completion suggestions, but we disable them by default.

name: t.ClassVar[str] = 'zsh'

shell executable.

supports_scripts: bool = True

The zsh completer supports script invocations.

template: str = 'shell_complete/zsh.sh'

The template used to render the zsh completion script.

class django_typer.shells.powershell.PowerShellComplete(cli=None, ctx_args={}, prog_name='', complete_var='', command=None, command_str=None, command_args=None, template=None, color=None, color_default=True, **kwargs)

This completer class supports the PowerShell versions < 6. See PwshComplete for versions >= 6.

Completion scripts are installed into the user’s profile file.

Returned suggestions are delimited by :::. Each suggestion is one one line.

Parameters:

• cli (Command | None)

• ctx_args (MutableMapping[str, Any])

• prog_name (str)

• complete_var (str)

• command (ShellCompletion | None)

• command_str (str | None)

• command_args (List[str] | None)

• template (str | None)

• color (bool | None)

• color_default (bool)

color: bool = False

PowerShell does support ansi control codes in completion suggestions, but we disable them by default.

name: t.ClassVar[str] = 'powershell'

shell executable.

supports_scripts: bool = False

PowerShell does not support script invocations.

template: str = 'shell_complete/powershell.ps1'

The template used to render the powershell completion script.

class django_typer.shells.powershell.PwshComplete(cli=None, ctx_args={}, prog_name='', complete_var='', command=None, command_str=None, command_args=None, template=None, color=None, color_default=True, **kwargs)

This completer class supports the PowerShell versions >= 6. See PowerShellComplete for versions < 6.

All behaviors are the same as PowerShellComplete, except that pwsh is used instead of powershell.

Parameters:

• cli (Command | None)

• ctx_args (MutableMapping[str, Any])

• prog_name (str)

• complete_var (str)

• command (ShellCompletion | None)

• command_str (str | None)

• command_args (List[str] | None)

• template (str | None)

• color (bool | None)

• color_default (bool)

color: bool = False

PowerShell does support ansi control codes in completion suggestions, but we disable them by default.

name: t.ClassVar[str] = 'pwsh'

shell executable.

supports_scripts: bool = False

PowerShell does not support script invocations.

template: str = 'shell_complete/powershell.ps1'

The template used to render the powershell completion script.

class django_typer.shells.fish.FishComplete(cli=None, ctx_args={}, prog_name='', complete_var='', command=None, command_str=None, command_args=None, template=None, color=None, color_default=True, **kwargs)

This completer class supports the fish shell. Completion scripts are installed in the ~/.config/fish/completions directory.

Returned suggestions are formatted as type,value[ help]. Each suggestion is on one line and if no help is provided, the help text including the tab delimiter is omitted.

Parameters:

• cli (Command | None)

• ctx_args (MutableMapping[str, Any])

• prog_name (str)

• complete_var (str)

• command (ShellCompletion | None)

• command_str (str | None)

• command_args (List[str] | None)

• template (str | None)

• color (bool | None)

• color_default (bool)

color: bool = False

Fish does not support ansi control codes.

name: t.ClassVar[str] = 'fish'

shell executable.

supports_scripts: bool = False

Fish does not support script invocations.

template: str = 'shell_complete/fish.fish'

The template used to render the fish completion script.