mafw.tools.script_completion_tools

Common tools for shell completion of MAFw scripts.

Added in version 2.2: Add helper functions for the handling of script completion.

Functions

`check_ci_completion_guard`()	Check if the current environment is a CI environment.
`is_script_already_installed`(tool_name, shell)	Check if the completion script for the tool is already installed.

mafw.tools.script_completion_tools._activation_script_path(shell: str) → Path[source]

Build the activation script path for a shell.

Parameters:: shell (str) – Resolved shell name.
Returns:: Target activation script path.
Return type:: pathlib.Path

mafw.tools.script_completion_tools._completion_marker_block(shell: str) → str[source]

Build the activation block appended to the environment activation script.

This block executes all files in $VIRTUAL_ENV/share/mafw/*_completion.<ext>.

Parameters:: shell (str) – Resolved shell name.
Returns:: Marker block to append to the activation file.
Return type:: str

mafw.tools.script_completion_tools._completion_script_path(tool_name: str, shell: str) → Path[source]

Build the completion script path inside the active virtual environment.

Parameters:

tool_name (str) – The name of the tool (e.g., ‘mafw’, ‘multiversion-doc’, ‘release-mgt’).
shell (str) – Resolved shell name.

Returns:

Target completion script path.

Return type:

pathlib.Path

mafw.tools.script_completion_tools._completion_shell_from_env(shell_path: str | None) → str[source]

Resolve a completion shell from $SHELL.

The resolver supports the shells handled by Click completion generation: bash, zsh, and fish.

Parameters:: shell_path (str | None) – The raw shell path as exposed by the environment.
Returns:: The normalized shell name.
Return type:: str
Raises:: click.ClickException – If the shell cannot be determined or is unsupported.

mafw.tools.script_completion_tools._completion_source_script(tool_name: str, shell: str) → str[source]

Generate the Click completion source script for the requested shell.

Parameters:

tool_name (str) – The name of the tool.
shell (str) – Resolved shell name.

Returns:

Completion script content.

Return type:

str

mafw.tools.script_completion_tools._install_completion(tool_name: str, shell: str, force: bool, script_path: Path) → Path[source]

Install Click completion for the requested shell.

Parameters:

tool_name (str) – The name of the tool.
shell (str) – Resolved shell name.
force (bool) – Reinstall even if completion is already loaded.
script_path (pathlib.Path) – The target path for the completion script.

Returns:

Installed completion script path.

Return type:

pathlib.Path

mafw.tools.script_completion_tools._resolve_completion_shell(shell: str) → str[source]

Normalize the requested completion shell.

Parameters:: shell (str) – Shell selector from the CLI.
Returns:: The resolved supported shell name.
Return type:: str
Raises:: click.ClickException – If the shell is unsupported.

mafw.tools.script_completion_tools._strip_completion_marker_block(content: str) → str[source]

Remove the completion block delimited by the MAFw markers.

Parameters:: content (str) – Activation script content.
Returns:: Content without the MAFw completion block.
Return type:: str

mafw.tools.script_completion_tools._uninstall_completion_files(tool_name: str, shell: str | None = None) → None[source]

Remove installed completion files and activation hooks.

Parameters:

tool_name (str) – The name of the tool.
shell (str | None) – Optional shell selector. When omitted, all completion files for the tool are removed.

mafw.tools.script_completion_tools._virtualenv_root() → Path[source]

Return the active virtual environment root.

Returns:: Active virtual environment path.
Return type:: pathlib.Path
Raises:: click.ClickException – If VIRTUAL_ENV is missing.

mafw.tools.script_completion_tools.check_ci_completion_guard() → None[source]

Check if the current environment is a CI environment.

If the CI environment variable is set, the function prints an informational message and exits the process with code 0.

mafw.tools.script_completion_tools.is_script_already_installed(tool_name: str, shell: str) → bool[source]

Check if the completion script for the tool is already installed.

Parameters:

tool_name (str) – The name of the tool.
shell (str) – Resolved shell name.

Returns:

True if the completion script exists, False otherwise.

Return type:

bool