Coverage for src / mafw / tools / click_extensions.py: 99%

1# Copyright 2025–2026 European Union 

2# Author: Bulgheroni Antonio (antonio.bulgheroni@ec.europa.eu) 

3# SPDX-License-Identifier: EUPL-1.2 

4""" 

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

6 

7This module centralizes the command abbreviation behavior used by the 

8``mafw`` executable and the development tools so nested command groups can 

9inherit the same resolution policy without repeating the ``cls=...`` 

10configuration. It also provides common helper functions for shell completion 

11installation and management across all MAFw CLI tools. 

12 

13.. versionadded:: 2.2 

14 

15Authors 

16------- 

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

18""" 

19 

20from __future__ import annotations 

21 

22import collections.abc as cabc 

23import os 

24import pathlib 

25import re 

26import sys 

27import warnings 

28from typing import TYPE_CHECKING, Any, Dict, Optional 

29 

30import click 

31 

32from mafw.tools.shell_tools import CONSOLE, run_stdout 

33 

34if TYPE_CHECKING: 

35 pass 

36 

37 

38class DeprecatedOption(click.Option): 

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

40 

41 Use this class as ``cls=DeprecatedOption`` in a ``@click.option`` decorator to 

42 mark an option as deprecated. The warning is only emitted when the user 

43 explicitly provides the option on the command line; default-value resolution 

44 does **not** trigger the warning. The resolved value is passed through to the 

45 command callback unchanged. 

46 

47 :param deprecated_message: Warning text emitted when the option is explicitly 

48 provided on the command line. 

49 :type deprecated_message: str 

50 

51 .. versionadded:: 2.2 

52 """ 

53 

54 def __init__(self, *args: Any, deprecated_message: str = '', **kwargs: Any) -> None: 

55 self.deprecated_message = deprecated_message 

56 super().__init__(*args, **kwargs) 

57 if self.help: 57 ↛ exitline 57 didn't return from function '__init__' because the condition on line 57 was always true

58 self.help = f'(DEPRECATED) {self.help}' 

59 

60 def consume_value( 

61 self, ctx: click.Context, opts: cabc.Mapping[str, click.Parameter] 

62 ) -> tuple[Any, click.core.ParameterSource]: 

63 """Intercept value consumption to detect explicit CLI usage. 

64 

65 :param ctx: Current Click context. 

66 :type ctx: click.Context 

67 :param opts: Parsed option tokens from the command line. 

68 :type opts: Mapping[str, click.Parameter] 

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

70 :rtype: tuple[Any, click.core.ParameterSource] 

71 """ 

72 value, source = super().consume_value(ctx, opts) 

73 if source == click.core.ParameterSource.COMMANDLINE: 

74 warnings.warn(self.deprecated_message, DeprecationWarning, stacklevel=1) 

75 return value, source 

76 

77 

78class AbbreviateGroup(click.Group): 

79 """Click group that resolves unique command prefixes and catches DevtoolsError.""" 

80 

81 group_class: type[click.Group] = click.Group 

82 

83 def invoke(self, ctx: click.Context) -> Any: 

84 """Invoke the group, catching DevtoolsError and converting to ClickException.""" 

85 from mafw.devtools import DevtoolsError 

86 

87 try: 

88 return super().invoke(ctx) 

89 except DevtoolsError as exc: 

90 raise click.ClickException(str(exc)) from exc 

91 

92 def get_command(self, ctx: click.Context, cmd_name: str) -> click.Command | None: 

93 """Return a command by exact name or a unique abbreviation.""" 

94 # let's give it a try to the cmd_name. if the user provided the full command, 

95 # then we might be lucky and get it working right away, otherwise we will have to try 

96 # to get the command using the abbreviations. 

97 rv = super().get_command(ctx, cmd_name) 

98 if rv is not None: 

99 return rv 

100 

101 matches = [name for name in self.list_commands(ctx) if name.startswith(cmd_name)] 

102 if not matches: 

103 return None 

104 if len(matches) == 1: 

105 return click.Group.get_command(self, ctx, matches[0]) 

106 ctx.fail(f'Too many matches: {", ".join(sorted(matches))}') 

107 

108 def resolve_command( 

109 self, ctx: click.Context, args: list[str] 

110 ) -> tuple[str | None, click.Command | None, list[str]]: 

111 """Return the canonical command name for abbreviated commands.""" 

112 _, cmd, args = super().resolve_command(ctx, args) 

113 if TYPE_CHECKING: 

114 assert isinstance(cmd, click.Command) 

115 return cmd.name if cmd is not None else None, cmd, args 

116 

117 

118AbbreviateGroup.group_class = AbbreviateGroup 

119 

120 

121COMPLETION_SHELLS: Dict[str, str] = {'bash': 'bash_source', 'zsh': 'zsh_source', 'fish': 'fish_source'} 

122 

123 

124def check_ci_completion_guard() -> None: 

125 """ 

126 Check if the current environment is a CI environment. 

127 

128 If the ``CI`` environment variable is set, the function prints an 

129 informational message and exits the process with code 0. 

130 """ 

131 if os.environ.get('CI'): 

132 CONSOLE.print('This command is not compatible with the CI environment.') 

133 sys.exit(0) 

134 

135 

136def completion_shell_from_env(shell_path: Optional[str]) -> str: 

137 """ 

138 Resolve a completion shell from ``$SHELL``. 

139 

140 The resolver supports the shells handled by Click completion generation: 

141 ``bash``, ``zsh``, and ``fish``. 

142 

143 :param shell_path: The raw shell path as exposed by the environment. 

144 :type shell_path: str | None 

145 :return: The normalized shell name. 

146 :rtype: str 

147 :raises click.ClickException: If the shell cannot be determined or is unsupported. 

148 """ 

149 if not shell_path: 

150 raise click.ClickException('Unable to infer a shell from $SHELL. Supported shells: bash, fish, zsh.') 

151 shell = pathlib.Path(shell_path).name 

152 if shell not in COMPLETION_SHELLS: 

153 supported = ', '.join(sorted(COMPLETION_SHELLS)) 

154 raise click.ClickException(f'Unsupported shell "{shell}". Supported shells: {supported}.') 

155 return shell 

156 

157 

158def resolve_completion_shell(shell: str) -> str: 

159 """ 

160 Normalize the requested completion shell. 

161 

162 :param shell: Shell selector from the CLI. 

163 :type shell: str 

164 :return: The resolved supported shell name. 

165 :rtype: str 

166 :raises click.ClickException: If the shell is unsupported. 

167 """ 

168 if shell == 'auto': 

169 return completion_shell_from_env(os.environ.get('SHELL')) 

170 if shell not in COMPLETION_SHELLS: 

171 supported = ', '.join(['auto', *sorted(COMPLETION_SHELLS)]) 

172 raise click.ClickException(f'Unsupported shell "{shell}". Supported shells: {supported}.') 

173 return shell 

174 

175 

176def _virtualenv_root() -> pathlib.Path: 

177 """ 

178 Return the active virtual environment root. 

179 

180 :return: Active virtual environment path. 

181 :rtype: pathlib.Path 

182 :raises click.ClickException: If ``VIRTUAL_ENV`` is missing. 

183 """ 

184 virtual_env = os.environ.get('VIRTUAL_ENV') 

185 if not virtual_env: 

186 raise click.ClickException('VIRTUAL_ENV is not set. Activate a virtual environment first.') 

187 return pathlib.Path(virtual_env) 

188 

189 

190def completion_script_path(tool_name: str, shell: str) -> pathlib.Path: 

191 """ 

192 Build the completion script path inside the active virtual environment. 

193 

194 :param tool_name: The name of the tool (e.g., 'mafw', 'multiversion-doc', 'release-mgt'). 

195 :type tool_name: str 

196 :param shell: Resolved shell name. 

197 :type shell: str 

198 :return: Target completion script path. 

199 :rtype: pathlib.Path 

200 """ 

201 suffix = {'bash': '.bash', 'zsh': '.zsh', 'fish': '.fish'}[shell] 

202 return _virtualenv_root() / 'share' / 'mafw' / f'{tool_name}_completion{suffix}' 

203 

204 

205def is_script_already_installed(tool_name: str, shell: str) -> bool: 

206 """ 

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

208 

209 :param tool_name: The name of the tool. 

210 :type tool_name: str 

211 :param shell: Resolved shell name. 

212 :type shell: str 

213 :return: True if the completion script exists, False otherwise. 

214 :rtype: bool 

215 """ 

216 return completion_script_path(tool_name, shell).exists() 

217 

218 

219def _activation_script_path(shell: str) -> pathlib.Path: 

220 """ 

221 Build the activation script path for a shell. 

222 

223 :param shell: Resolved shell name. 

224 :type shell: str 

225 :return: Target activation script path. 

226 :rtype: pathlib.Path 

227 """ 

228 if shell == 'fish': 

229 return _virtualenv_root() / 'bin' / 'activate.fish' 

230 return _virtualenv_root() / 'bin' / 'activate' 

231 

232 

233def completion_source_script(tool_name: str, shell: str) -> str: 

234 """ 

235 Generate the Click completion source script for the requested shell. 

236 

237 :param tool_name: The name of the tool. 

238 :type tool_name: str 

239 :param shell: Resolved shell name. 

240 :type shell: str 

241 :return: Completion script content. 

242 :rtype: str 

243 """ 

244 completion_env = COMPLETION_SHELLS[shell] 

245 # Use underscores and uppercase for the environment variable as Click expects 

246 env_var = f'_{tool_name.upper().replace("-", "_")}_COMPLETE' 

247 return run_stdout([tool_name], env={env_var: completion_env}, quiet=True) 

248 

249 

250def _completion_marker_block(shell: str) -> str: 

251 """ 

252 Build the activation block appended to the environment activation script. 

253 

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

255 

256 :param shell: Resolved shell name. 

257 :type shell: str 

258 :return: Marker block to append to the activation file. 

259 :rtype: str 

260 """ 

261 if shell == 'fish': 

262 return ( 

263 '# >>> MAFw completion >>>\n' 

264 'for file in "$VIRTUAL_ENV/share/mafw/"*_completion.fish\n' 

265 ' if test -f "$file"\n' 

266 ' source "$file"\n' 

267 ' end\n' 

268 'end\n' 

269 '# <<< MAFw completion <<<\n' 

270 ) 

271 return ( 

272 '# >>> MAFw completion >>>\n' 

273 'case "$SHELL" in\n' 

274 ' *zsh*) ext="zsh" ;;\n' 

275 ' *) ext="bash" ;;\n' 

276 'esac\n' 

277 'for file in "$VIRTUAL_ENV/share/mafw/"*_completion."$ext"; do\n' 

278 ' if [ -f "$file" ]; then\n' 

279 ' . "$file"\n' 

280 ' fi\n' 

281 'done\n' 

282 '# <<< MAFw completion <<<\n' 

283 ) 

284 

285 

286def _strip_completion_marker_block(content: str) -> str: 

287 """ 

288 Remove the completion block delimited by the MAFw markers. 

289 

290 :param content: Activation script content. 

291 :type content: str 

292 :return: Content without the MAFw completion block. 

293 :rtype: str 

294 """ 

295 pattern = re.compile(r'\n?# >>> MAFw completion >>>\n.*?\n# <<< MAFw completion <<<\n?', re.S) 

296 return pattern.sub('\n', content) 

297 

298 

299def uninstall_completion_files(tool_name: str, shell: Optional[str] = None) -> None: 

300 """ 

301 Remove installed completion files and activation hooks. 

302 

303 :param tool_name: The name of the tool. 

304 :type tool_name: str 

305 :param shell: Optional shell selector. When omitted, all completion files for the tool are removed. 

306 :type shell: str | None 

307 """ 

308 virtual_env = _virtualenv_root() 

309 share_dir = virtual_env / 'share' / 'mafw' 

310 

311 if share_dir.exists(): 

312 if shell is None: 

313 targets = list(share_dir.glob(f'{tool_name}_completion.*')) 

314 else: 

315 targets = [completion_script_path(tool_name, shell)] 

316 

317 for path in targets: 

318 if path.exists(): 

319 path.unlink() 

320 

321 # Check if any other completion files remain 

322 remaining = list(share_dir.glob('*_completion.*')) if share_dir.exists() else [] 

323 

324 if not remaining: 

325 for activation_path in (virtual_env / 'bin' / 'activate', virtual_env / 'bin' / 'activate.fish'): 

326 if not activation_path.exists(): 

327 continue 

328 content = activation_path.read_text(encoding='utf-8') 

329 updated = _strip_completion_marker_block(content) 

330 if updated != content: 

331 activation_path.write_text(updated.lstrip('\n'), encoding='utf-8') 

332 

333 

334def install_completion(tool_name: str, shell: str, force: bool, script_path: pathlib.Path) -> pathlib.Path: 

335 """ 

336 Install Click completion for the requested shell. 

337 

338 :param tool_name: The name of the tool. 

339 :type tool_name: str 

340 :param shell: Resolved shell name. 

341 :type shell: str 

342 :param force: Reinstall even if completion is already loaded. 

343 :type force: bool 

344 :param script_path: The target path for the completion script. 

345 :type script_path: pathlib.Path 

346 :return: Installed completion script path. 

347 :rtype: pathlib.Path 

348 """ 

349 if force: 

350 uninstall_completion_files(tool_name, shell) 

351 

352 script_path.parent.mkdir(parents=True, exist_ok=True) 

353 activation_path = _activation_script_path(shell) 

354 

355 script_text = completion_source_script(tool_name, shell) 

356 script_path.write_text(script_text, encoding='utf-8') 

357 

358 activation_path.parent.mkdir(parents=True, exist_ok=True) 

359 activation_content = activation_path.read_text(encoding='utf-8') if activation_path.exists() else '' 

360 # Add marker block if not present 

361 if '# >>> MAFw completion >>>' not in activation_content: 

362 activation_content = activation_content.rstrip('\n') + '\n\n' + _completion_marker_block(shell) 

363 activation_path.write_text(activation_content, encoding='utf-8') 

364 

365 return script_path