# Copyright 2025–2026 European Union
# Author: Bulgheroni Antonio (antonio.bulgheroni@ec.europa.eu)
# SPDX-License-Identifier: EUPL-1.2
"""
Common tools for shell completion of MAFw scripts.
.. versionadded:: 2.2 Add helper functions for the handling of script completion.
"""
import os
import pathlib
import re
import sys
from typing import Dict, Optional
import click
from mafw.tools.shell_tools import CONSOLE, run_stdout
COMPLETION_SHELLS: Dict[str, str] = {'bash': 'bash_source', 'zsh': 'zsh_source', 'fish': 'fish_source'}
[docs]
def check_ci_completion_guard() -> None:
"""
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.
"""
if os.environ.get('CI'):
CONSOLE.print('This command is not compatible with the CI environment.')
sys.exit(0)
[docs]
def _completion_shell_from_env(shell_path: Optional[str]) -> str:
"""
Resolve a completion shell from ``$SHELL``.
The resolver supports the shells handled by Click completion generation:
``bash``, ``zsh``, and ``fish``.
:param shell_path: The raw shell path as exposed by the environment.
:type shell_path: str | None
:return: The normalized shell name.
:rtype: str
:raises click.ClickException: If the shell cannot be determined or is unsupported.
"""
if not shell_path:
raise click.ClickException('Unable to infer a shell from $SHELL. Supported shells: bash, fish, zsh.')
shell = pathlib.Path(shell_path).name
if shell not in COMPLETION_SHELLS:
supported = ', '.join(sorted(COMPLETION_SHELLS))
raise click.ClickException(f'Unsupported shell "{shell}". Supported shells: {supported}.')
return shell
[docs]
def _resolve_completion_shell(shell: str) -> str:
"""
Normalize the requested completion shell.
:param shell: Shell selector from the CLI.
:type shell: str
:return: The resolved supported shell name.
:rtype: str
:raises click.ClickException: If the shell is unsupported.
"""
if shell == 'auto':
return _completion_shell_from_env(os.environ.get('SHELL'))
if shell not in COMPLETION_SHELLS:
supported = ', '.join(['auto', *sorted(COMPLETION_SHELLS)])
raise click.ClickException(f'Unsupported shell "{shell}". Supported shells: {supported}.')
return shell
[docs]
def _virtualenv_root() -> pathlib.Path:
"""
Return the active virtual environment root.
:return: Active virtual environment path.
:rtype: pathlib.Path
:raises click.ClickException: If ``VIRTUAL_ENV`` is missing.
"""
virtual_env = os.environ.get('VIRTUAL_ENV')
if not virtual_env:
raise click.ClickException('VIRTUAL_ENV is not set. Activate a virtual environment first.')
return pathlib.Path(virtual_env)
[docs]
def _completion_script_path(tool_name: str, shell: str) -> pathlib.Path:
"""
Build the completion script path inside the active virtual environment.
:param tool_name: The name of the tool (e.g., 'mafw', 'multiversion-doc', 'release-mgt').
:type tool_name: str
:param shell: Resolved shell name.
:type shell: str
:return: Target completion script path.
:rtype: pathlib.Path
"""
suffix = {'bash': '.bash', 'zsh': '.zsh', 'fish': '.fish'}[shell]
return _virtualenv_root() / 'share' / 'mafw' / f'{tool_name}_completion{suffix}'
[docs]
def is_script_already_installed(tool_name: str, shell: str) -> bool:
"""
Check if the completion script for the tool is already installed.
:param tool_name: The name of the tool.
:type tool_name: str
:param shell: Resolved shell name.
:type shell: str
:return: True if the completion script exists, False otherwise.
:rtype: bool
"""
return _completion_script_path(tool_name, shell).exists()
[docs]
def _activation_script_path(shell: str) -> pathlib.Path:
"""
Build the activation script path for a shell.
:param shell: Resolved shell name.
:type shell: str
:return: Target activation script path.
:rtype: pathlib.Path
"""
if shell == 'fish':
return _virtualenv_root() / 'bin' / 'activate.fish'
return _virtualenv_root() / 'bin' / 'activate'
[docs]
def _completion_source_script(tool_name: str, shell: str) -> str:
"""
Generate the Click completion source script for the requested shell.
:param tool_name: The name of the tool.
:type tool_name: str
:param shell: Resolved shell name.
:type shell: str
:return: Completion script content.
:rtype: str
"""
completion_env = COMPLETION_SHELLS[shell]
# Use underscores and uppercase for the environment variable as Click expects
env_var = f'_{tool_name.upper().replace("-", "_")}_COMPLETE'
return run_stdout([tool_name], env={env_var: completion_env}, quiet=True)
[docs]
def _completion_marker_block(shell: str) -> str:
"""
Build the activation block appended to the environment activation script.
This block executes all files in `$VIRTUAL_ENV/share/mafw/*_completion.<ext>`.
:param shell: Resolved shell name.
:type shell: str
:return: Marker block to append to the activation file.
:rtype: str
"""
if shell == 'fish':
return (
'# >>> MAFw completion >>>\n'
'for file in "$VIRTUAL_ENV/share/mafw/"*_completion.fish\n'
' if test -f "$file"\n'
' source "$file"\n'
' end\n'
'end\n'
'# <<< MAFw completion <<<\n'
)
return (
'# >>> MAFw completion >>>\n'
'case "$SHELL" in\n'
' *zsh*) ext="zsh" ;;\n'
' *) ext="bash" ;;\n'
'esac\n'
'for file in "$VIRTUAL_ENV/share/mafw/"*_completion."$ext"; do\n'
' if [ -f "$file" ]; then\n'
' . "$file"\n'
' fi\n'
'done\n'
'# <<< MAFw completion <<<\n'
)
[docs]
def _strip_completion_marker_block(content: str) -> str:
"""
Remove the completion block delimited by the MAFw markers.
:param content: Activation script content.
:type content: str
:return: Content without the MAFw completion block.
:rtype: str
"""
pattern = re.compile(r'\n?# >>> MAFw completion >>>\n.*?\n# <<< MAFw completion <<<\n?', re.S)
return pattern.sub('\n', content)
[docs]
def _uninstall_completion_files(tool_name: str, shell: Optional[str] = None) -> None:
"""
Remove installed completion files and activation hooks.
:param tool_name: The name of the tool.
:type tool_name: str
:param shell: Optional shell selector. When omitted, all completion files for the tool are removed.
:type shell: str | None
"""
virtual_env = _virtualenv_root()
share_dir = virtual_env / 'share' / 'mafw'
if share_dir.exists():
if shell is None:
targets = list(share_dir.glob(f'{tool_name}_completion.*'))
else:
targets = [_completion_script_path(tool_name, shell)]
for path in targets:
if path.exists():
path.unlink()
# Check if any other completion files remain
remaining = list(share_dir.glob('*_completion.*')) if share_dir.exists() else []
if not remaining:
for activation_path in (virtual_env / 'bin' / 'activate', virtual_env / 'bin' / 'activate.fish'):
if not activation_path.exists():
continue
content = activation_path.read_text(encoding='utf-8')
updated = _strip_completion_marker_block(content)
if updated != content:
activation_path.write_text(updated.lstrip('\n'), encoding='utf-8')
[docs]
def _install_completion(tool_name: str, shell: str, force: bool, script_path: pathlib.Path) -> pathlib.Path:
"""
Install Click completion for the requested shell.
:param tool_name: The name of the tool.
:type tool_name: str
:param shell: Resolved shell name.
:type shell: str
:param force: Reinstall even if completion is already loaded.
:type force: bool
:param script_path: The target path for the completion script.
:type script_path: pathlib.Path
:return: Installed completion script path.
:rtype: pathlib.Path
"""
if force:
_uninstall_completion_files(tool_name, shell)
script_path.parent.mkdir(parents=True, exist_ok=True)
activation_path = _activation_script_path(shell)
script_text = _completion_source_script(tool_name, shell)
script_path.write_text(script_text, encoding='utf-8')
activation_path.parent.mkdir(parents=True, exist_ok=True)
activation_content = activation_path.read_text(encoding='utf-8') if activation_path.exists() else ''
# Add marker block if not present
if '# >>> MAFw completion >>>' not in activation_content:
activation_content = activation_content.rstrip('\n') + '\n\n' + _completion_marker_block(shell)
activation_path.write_text(activation_content, encoding='utf-8')
return script_path