mafw.tools.click_extensions

Reusable Click group classes and shell completion tools for MAFw command-line interfaces.

This module centralizes the command abbreviation behavior used by the mafw executable and the development tools so nested command groups can inherit the same resolution policy without repeating the cls=... configuration. It also provides common helper functions for shell completion installation and management across all MAFw CLI tools.

Added in version 2.2.

Authors

Bulgheroni Antonio <antonio.bulgheroni@ec.europa.eu>

Functions

`check_ci_completion_guard`()	Check if the current environment is a CI environment.
`completion_script_path`(tool_name, shell)	Build the completion script path inside the active virtual environment.
`completion_shell_from_env`(shell_path)	Resolve a completion shell from `$SHELL`.
`completion_source_script`(tool_name, shell)	Generate the Click completion source script for the requested shell.
`install_completion`(tool_name, shell, force, ...)	Install Click completion for the requested shell.
`is_script_already_installed`(tool_name, shell)	Check if the completion script for the tool is already installed.
`resolve_completion_shell`(shell)	Normalize the requested completion shell.
`uninstall_completion_files`(tool_name[, shell])	Remove installed completion files and activation hooks.

Classes

`AbbreviateGroup`([name, commands, ...])	Click group that resolves unique command prefixes and catches DevtoolsError.
`DeprecatedOption`(*args[, deprecated_message])	A Click Option subclass that emits a DeprecationWarning when explicitly used.

class mafw.tools.click_extensions.AbbreviateGroup(name: str | None = None, commands: MutableMapping[str, Command] | Sequence[Command] | None = None, invoke_without_command: bool = False, no_args_is_help: bool | None = None, subcommand_metavar: str | None = None, chain: bool = False, result_callback: Callable[[...], Any] | None = None, **kwargs: Any)[source]

Bases: Group

Click group that resolves unique command prefixes and catches DevtoolsError.

group_class: alias of AbbreviateGroup

get_command(ctx: Context, cmd_name: str) → Command | None[source]: Return a command by exact name or a unique abbreviation.

invoke(ctx: Context) → Any[source]: Invoke the group, catching DevtoolsError and converting to ClickException.

resolve_command(ctx: Context, args: list[str]) → tuple[str | None, Command | None, list[str]][source]: Return the canonical command name for abbreviated commands.

class mafw.tools.click_extensions.DeprecatedOption(*args: Any, deprecated_message: str = '', **kwargs: Any)[source]

Bases: Option

A Click Option subclass that emits a DeprecationWarning when explicitly used.

Use this class as cls=DeprecatedOption in a @click.option decorator to mark an option as deprecated. The warning is only emitted when the user explicitly provides the option on the command line; default-value resolution does not trigger the warning. The resolved value is passed through to the command callback unchanged.

Parameters:: deprecated_message (str) – Warning text emitted when the option is explicitly provided on the command line.

Added in version 2.2.

consume_value(ctx: Context, opts: Mapping[str, Parameter]) → tuple[Any, ParameterSource][source]

Intercept value consumption to detect explicit CLI usage.

Parameters:

ctx (click.Context) – Current Click context.
opts (Mapping[str, click.Parameter]) – Parsed option tokens from the command line.

Returns:

Tuple of (value, source) as returned by the parent implementation.

Return type:

tuple[Any, click.core.ParameterSource]

mafw.tools.click_extensions._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.click_extensions._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.click_extensions._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.click_extensions._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.click_extensions.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.click_extensions.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.click_extensions.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.click_extensions.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.click_extensions.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.click_extensions.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

mafw.tools.click_extensions.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.click_extensions.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.