Coverage for src/debputy/commands/debputy_cmd/plugin_cmds.py: 13%

1import argparse 

2import itertools 

3import operator 

4import os 

5import sys 

6from itertools import chain 

7from typing import ( 

8 Sequence, 

9 Union, 

10 Tuple, 

11 Iterable, 

12 Any, 

13 Optional, 

14 Type, 

15 Mapping, 

16 Callable, 

17) 

18 

19from debputy import DEBPUTY_DOC_ROOT_DIR 

20from debputy.commands.debputy_cmd.context import ( 

21 CommandContext, 

22 add_arg, 

23 ROOT_COMMAND, 

24) 

25from debputy.commands.debputy_cmd.dc_util import flatten_ppfs 

26from debputy.commands.debputy_cmd.output import ( 

27 _stream_to_pager, 

28 _output_styling, 

29 OutputStylingBase, 

30) 

31from debputy.exceptions import DebputySubstitutionError 

32from debputy.filesystem_scan import build_virtual_fs 

33from debputy.manifest_parser.base_types import TypeMapping 

34from debputy.manifest_parser.declarative_parser import ( 

35 DeclarativeMappingInputParser, 

36 DeclarativeNonMappingInputParser, 

37 BASIC_SIMPLE_TYPES, 

38) 

39from debputy.manifest_parser.parser_data import ParserContextData 

40from debputy.manifest_parser.parser_doc import render_rule 

41from debputy.manifest_parser.util import unpack_type, AttributePath 

42from debputy.packager_provided_files import detect_all_packager_provided_files 

43from debputy.plugin.api.example_processing import ( 

44 process_discard_rule_example, 

45 DiscardVerdict, 

46) 

47from debputy.plugin.api.impl import plugin_metadata_for_debputys_own_plugin 

48from debputy.plugin.api.impl_types import ( 

49 PackagerProvidedFileClassSpec, 

50 PluginProvidedManifestVariable, 

51 DispatchingParserBase, 

52 DeclarativeInputParser, 

53 DebputyPluginMetadata, 

54 DispatchingObjectParser, 

55 SUPPORTED_DISPATCHABLE_TABLE_PARSERS, 

56 OPARSER_MANIFEST_ROOT, 

57 PluginProvidedDiscardRule, 

58 AutomaticDiscardRuleExample, 

59 MetadataOrMaintscriptDetector, 

60 PluginProvidedTypeMapping, 

61) 

62from debputy.plugin.api.spec import ( 

63 ParserDocumentation, 

64 reference_documentation, 

65 undocumented_attr, 

66 TypeMappingExample, 

67) 

68from debputy.substitution import Substitution 

69from debputy.util import _error, assume_not_none, _warn 

70 

71plugin_dispatcher = ROOT_COMMAND.add_dispatching_subcommand( 

72 "plugin", 

73 "plugin_subcommand", 

74 default_subcommand="--help", 

75 help_description="Interact with debputy plugins", 

76 metavar="command", 

77) 

78 

79plugin_list_cmds = plugin_dispatcher.add_dispatching_subcommand( 

80 "list", 

81 "plugin_subcommand_list", 

82 metavar="topic", 

83 default_subcommand="plugins", 

84 help_description="List plugins or things provided by plugins (unstable format)." 

85 " Pass `--help` *after* `list` get a topic listing", 

86) 

87 

88plugin_show_cmds = plugin_dispatcher.add_dispatching_subcommand( 

89 "show", 

90 "plugin_subcommand_show", 

91 metavar="topic", 

92 help_description="Show details about a plugin or things provided by plugins (unstable format)." 

93 " Pass `--help` *after* `show` get a topic listing", 

94) 

95 

96 

97def format_output_arg( 

98 default_format: str, 

99 allowed_formats: Sequence[str], 

100 help_text: str, 

101) -> Callable[[argparse.ArgumentParser], None]: 

102 if default_format not in allowed_formats: 102 ↛ 103line 102 didn't jump to line 103, because the condition on line 102 was never true

103 raise ValueError("The default format must be in the allowed_formats...") 

104 

105 def _configurator(argparser: argparse.ArgumentParser) -> None: 

106 argparser.add_argument( 

107 "--output-format", 

108 dest="output_format", 

109 default=default_format, 

110 choices=allowed_formats, 

111 help=help_text, 

112 ) 

113 

114 return _configurator 

115 

116 

117# To let --output-format=... "always" work 

118TEXT_ONLY_FORMAT = format_output_arg( 

119 "text", 

120 ["text"], 

121 "Select a given output format (options and output are not stable between releases)", 

122) 

123 

124 

125TEXT_CSV_FORMAT_NO_STABILITY_PROMISE = format_output_arg( 

126 "text", 

127 ["text", "csv"], 

128 "Select a given output format (options and output are not stable between releases)", 

129) 

130 

131 

132@plugin_list_cmds.register_subcommand( 

133 "plugins", 

134 help_description="List known plugins with their versions", 

135 argparser=TEXT_CSV_FORMAT_NO_STABILITY_PROMISE, 

136) 

137def _plugin_cmd_list_plugins(context: CommandContext) -> None: 

138 plugin_metadata_entries = context.load_plugins().plugin_data.values() 

139 # Because the "plugins" part is optional, we are not guaranteed that TEXT_CSV_FORMAT applies 

140 output_format = getattr(context.parsed_args, "output_format", "text") 

141 assert output_format in {"text", "csv"} 

142 with _stream_to_pager(context.parsed_args) as (fd, fo): 

143 fo.print_list_table( 

144 ["Plugin Name", "Plugin Path"], 

145 [(p.plugin_name, p.plugin_path) for p in plugin_metadata_entries], 

146 ) 

147 

148 

149def _path(path: str) -> str: 

150 if path.startswith("./"): 

151 return path[1:] 

152 return path 

153 

154 

155def _ppf_flags(ppf: PackagerProvidedFileClassSpec) -> str: 

156 flags = [] 

157 if ppf.allow_name_segment: 

158 flags.append("named") 

159 if ppf.allow_architecture_segment: 

160 flags.append("arch") 

161 if ppf.supports_priority: 

162 flags.append(f"priority={ppf.default_priority}") 

163 if ppf.packageless_is_fallback_for_all_packages: 

164 flags.append("main-all-fallback") 

165 if ppf.post_formatting_rewrite: 

166 flags.append("post-format-hook") 

167 return ",".join(flags) 

168 

169 

170@plugin_list_cmds.register_subcommand( 

171 ["used-packager-provided-files", "uppf", "u-p-p-f"], 

172 help_description="List packager provided files used by this package (debian/pkg.foo)", 

173 argparser=TEXT_ONLY_FORMAT, 

174) 

175def _plugin_cmd_list_uppf(context: CommandContext) -> None: 

176 ppf_table = context.load_plugins().packager_provided_files 

177 all_ppfs = detect_all_packager_provided_files( 

178 ppf_table, 

179 context.debian_dir, 

180 context.binary_packages(), 

181 ) 

182 requested_plugins = set(context.requested_plugins()) 

183 requested_plugins.add("debputy") 

184 all_detected_ppfs = list(flatten_ppfs(all_ppfs)) 

185 

186 used_ppfs = [ 

187 p 

188 for p in all_detected_ppfs 

189 if p.definition.debputy_plugin_metadata.plugin_name in requested_plugins 

190 ] 

191 inactive_ppfs = [ 

192 p 

193 for p in all_detected_ppfs 

194 if p.definition.debputy_plugin_metadata.plugin_name not in requested_plugins 

195 ] 

196 

197 if not used_ppfs and not inactive_ppfs: 

198 print("No packager provided files detected; not even a changelog... ?") 

199 return 

200 

201 with _stream_to_pager(context.parsed_args) as (fd, fo): 

202 if used_ppfs: 

203 headers: Sequence[Union[str, Tuple[str, str]]] = [ 

204 "File", 

205 "Matched Stem", 

206 "Installed Into", 

207 "Installed As", 

208 ] 

209 fo.print_list_table( 

210 headers, 

211 [ 

212 ( 

213 ppf.path.path, 

214 ppf.definition.stem, 

215 ppf.package_name, 

216 "/".join(ppf.compute_dest()).lstrip("."), 

217 ) 

218 for ppf in sorted( 

219 used_ppfs, key=operator.attrgetter("package_name") 

220 ) 

221 ], 

222 ) 

223 

224 if inactive_ppfs: 

225 headers: Sequence[Union[str, Tuple[str, str]]] = [ 

226 "UNUSED FILE", 

227 "Matched Stem", 

228 "Installed Into", 

229 "Could Be Installed As", 

230 "If B-D Had", 

231 ] 

232 fo.print_list_table( 

233 headers, 

234 [ 

235 ( 

236 f"~{ppf.path.path}~", 

237 ppf.definition.stem, 

238 f"~{ppf.package_name}~", 

239 "/".join(ppf.compute_dest()).lstrip("."), 

240 f"debputy-plugin-{ppf.definition.debputy_plugin_metadata.plugin_name}", 

241 ) 

242 for ppf in sorted( 

243 inactive_ppfs, key=operator.attrgetter("package_name") 

244 ) 

245 ], 

246 ) 

247 

248 

249@plugin_list_cmds.register_subcommand( 

250 ["packager-provided-files", "ppf", "p-p-f"], 

251 help_description="List packager provided file definitions (debian/pkg.foo)", 

252 argparser=TEXT_CSV_FORMAT_NO_STABILITY_PROMISE, 

253) 

254def _plugin_cmd_list_ppf(context: CommandContext) -> None: 

255 ppfs: Iterable[PackagerProvidedFileClassSpec] 

256 ppfs = context.load_plugins().packager_provided_files.values() 

257 with _stream_to_pager(context.parsed_args) as (fd, fo): 

258 headers: Sequence[Union[str, Tuple[str, str]]] = [ 

259 "Stem", 

260 "Installed As", 

261 ("Mode", ">"), 

262 "Features", 

263 "Provided by", 

264 ] 

265 fo.print_list_table( 

266 headers, 

267 [ 

268 ( 

269 ppf.stem, 

270 _path(ppf.installed_as_format), 

271 "0" + oct(ppf.default_mode)[2:], 

272 _ppf_flags(ppf), 

273 ppf.debputy_plugin_metadata.plugin_name, 

274 ) 

275 for ppf in sorted(ppfs, key=operator.attrgetter("stem")) 

276 ], 

277 ) 

278 

279 if os.path.isdir("debian/") and fo.output_format == "text": 

280 fo.print() 

281 fo.print( 

282 "Hint: You can use `debputy plugin list used-packager-provided-files` to have `debputy`", 

283 ) 

284 fo.print("list all the files in debian/ that matches these definitions.") 

285 

286 

287@plugin_list_cmds.register_subcommand( 

288 ["metadata-detectors"], 

289 help_description="List metadata detectors", 

290 argparser=TEXT_CSV_FORMAT_NO_STABILITY_PROMISE, 

291) 

292def _plugin_cmd_list_metadata_detectors(context: CommandContext) -> None: 

293 mds = list( 

294 chain.from_iterable( 

295 context.load_plugins().metadata_maintscript_detectors.values() 

296 ) 

297 ) 

298 

299 def _sort_key(md: "MetadataOrMaintscriptDetector") -> Any: 

300 return md.plugin_metadata.plugin_name, md.detector_id 

301 

302 with _stream_to_pager(context.parsed_args) as (fd, fo): 

303 fo.print_list_table( 

304 ["Provided by", "Detector Id"], 

305 [ 

306 (md.plugin_metadata.plugin_name, md.detector_id) 

307 for md in sorted(mds, key=_sort_key) 

308 ], 

309 ) 

310 

311 

312def _resolve_variable_for_list( 

313 substitution: Substitution, 

314 variable: PluginProvidedManifestVariable, 

315) -> str: 

316 var = "{{" + variable.variable_name + "}}" 

317 try: 

318 value = substitution.substitute(var, "CLI request") 

319 except DebputySubstitutionError: 

320 value = None 

321 return _render_manifest_variable_value(value) 

322 

323 

324def _render_manifest_variable_flag(variable: PluginProvidedManifestVariable) -> str: 

325 flags = [] 

326 if variable.is_for_special_case: 

327 flags.append("special-use-case") 

328 if variable.is_internal: 

329 flags.append("internal") 

330 return ",".join(flags) 

331 

332 

333def _render_list_filter(v: Optional[bool]) -> str: 

334 if v is None: 

335 return "N/A" 

336 return "shown" if v else "hidden" 

337 

338 

339@plugin_list_cmds.register_subcommand( 

340 ["manifest-variables"], 

341 help_description="List plugin provided manifest variables (such as `{{path:FOO}}`)", 

342) 

343def plugin_cmd_list_manifest_variables(context: CommandContext) -> None: 

344 variables = context.load_plugins().manifest_variables 

345 substitution = context.substitution.with_extra_substitutions( 

346 PACKAGE="<package-name>" 

347 ) 

348 parsed_args = context.parsed_args 

349 show_special_case_vars = parsed_args.show_special_use_variables 

350 show_token_vars = parsed_args.show_token_variables 

351 show_all_vars = parsed_args.show_all_variables 

352 

353 def _include_var(var: PluginProvidedManifestVariable) -> bool: 

354 if show_all_vars: 

355 return True 

356 if var.is_internal: 

357 return False 

358 if var.is_for_special_case and not show_special_case_vars: 

359 return False 

360 if var.is_token and not show_token_vars: 

361 return False 

362 return True 

363 

364 with _stream_to_pager(context.parsed_args) as (fd, fo): 

365 fo.print_list_table( 

366 ["Variable (use via: `{{ NAME }}`)", "Value", "Flag", "Provided by"], 

367 [ 

368 ( 

369 k, 

370 _resolve_variable_for_list(substitution, var), 

371 _render_manifest_variable_flag(var), 

372 var.plugin_metadata.plugin_name, 

373 ) 

374 for k, var in sorted(variables.items()) 

375 if _include_var(var) 

376 ], 

377 ) 

378 

379 fo.print() 

380 

381 filters = [ 

382 ( 

383 "Token variables", 

384 show_token_vars if not show_all_vars else None, 

385 "--show-token-variables", 

386 ), 

387 ( 

388 "Special use variables", 

389 show_special_case_vars if not show_all_vars else None, 

390 "--show-special-case-variables", 

391 ), 

392 ] 

393 

394 fo.print_list_table( 

395 ["Variable type", "Value", "Option"], 

396 [ 

397 ( 

398 fname, 

399 _render_list_filter(value or show_all_vars), 

400 f"{option} OR --show-all-variables", 

401 ) 

402 for fname, value, option in filters 

403 ], 

404 ) 

405 

406 

407@plugin_cmd_list_manifest_variables.configure_handler 

408def list_manifest_variable_arg_parser( 

409 plugin_list_manifest_variables_parser: argparse.ArgumentParser, 

410) -> None: 

411 plugin_list_manifest_variables_parser.add_argument( 

412 "--show-special-case-variables", 

413 dest="show_special_use_variables", 

414 default=False, 

415 action="store_true", 

416 help="Show variables that are only used in special / niche cases", 

417 ) 

418 plugin_list_manifest_variables_parser.add_argument( 

419 "--show-token-variables", 

420 dest="show_token_variables", 

421 default=False, 

422 action="store_true", 

423 help="Show token (syntactical) variables like {{token:TAB}}", 

424 ) 

425 plugin_list_manifest_variables_parser.add_argument( 

426 "--show-all-variables", 

427 dest="show_all_variables", 

428 default=False, 

429 action="store_true", 

430 help="Show all variables regardless of type/kind (overrules other filter settings)", 

431 ) 

432 TEXT_ONLY_FORMAT(plugin_list_manifest_variables_parser) 

433 

434 

435def _parser_type_name(v: Union[str, Type[Any]]) -> str: 

436 if isinstance(v, str): 

437 return v if v != "<ROOT>" else "" 

438 return v.__name__ 

439 

440 

441@plugin_list_cmds.register_subcommand( 

442 ["pluggable-manifest-rules", "p-m-r", "pmr"], 

443 help_description="Pluggable manifest rules (such as install rules)", 

444 argparser=TEXT_CSV_FORMAT_NO_STABILITY_PROMISE, 

445) 

446def _plugin_cmd_list_manifest_rules(context: CommandContext) -> None: 

447 feature_set = context.load_plugins() 

448 

449 # Type hint to make the chain call easier for the type checker, which does not seem 

450 # to derive to this common base type on its own. 

451 base_type = Iterable[Tuple[Union[str, Type[Any]], DispatchingParserBase[Any]]] 

452 

453 parser_generator = feature_set.manifest_parser_generator 

454 table_parsers: base_type = parser_generator.dispatchable_table_parsers.items() 

455 object_parsers: base_type = parser_generator.dispatchable_object_parsers.items() 

456 

457 parsers = chain( 

458 table_parsers, 

459 object_parsers, 

460 ) 

461 

462 with _stream_to_pager(context.parsed_args) as (fd, fo): 

463 fo.print_list_table( 

464 ["Rule Name", "Rule Type", "Provided By"], 

465 [ 

466 ( 

467 rn, 

468 _parser_type_name(rt), 

469 pt.parser_for(rn).plugin_metadata.plugin_name, 

470 ) 

471 for rt, pt in parsers 

472 for rn in pt.registered_keywords() 

473 ], 

474 ) 

475 

476 

477@plugin_list_cmds.register_subcommand( 

478 ["automatic-discard-rules", "a-d-r"], 

479 help_description="List automatic discard rules", 

480 argparser=TEXT_CSV_FORMAT_NO_STABILITY_PROMISE, 

481) 

482def _plugin_cmd_list_automatic_discard_rules(context: CommandContext) -> None: 

483 auto_discard_rules = context.load_plugins().auto_discard_rules 

484 

485 with _stream_to_pager(context.parsed_args) as (fd, fo): 

486 fo.print_list_table( 

487 ["Name", "Provided By"], 

488 [ 

489 ( 

490 name, 

491 ppdr.plugin_metadata.plugin_name, 

492 ) 

493 for name, ppdr in auto_discard_rules.items() 

494 ], 

495 ) 

496 

497 

498def _render_manifest_variable_value(v: Optional[str]) -> str: 

499 if v is None: 

500 return "(N/A: Cannot resolve the variable)" 

501 v = v.replace("\n", "\\n").replace("\t", "\\t") 

502 return v 

503 

504 

505def _render_multiline_documentation( 

506 documentation: str, 

507 *, 

508 first_line_prefix: str = "Documentation: ", 

509 following_line_prefix: str = " ", 

510) -> None: 

511 current_prefix = first_line_prefix 

512 for line in documentation.splitlines(keepends=False): 

513 if line.isspace(): 

514 if not current_prefix.isspace(): 

515 print(current_prefix.rstrip()) 

516 current_prefix = following_line_prefix 

517 else: 

518 print() 

519 continue 

520 print(f"{current_prefix}{line}") 

521 current_prefix = following_line_prefix 

522 

523 

524@plugin_show_cmds.register_subcommand( 

525 ["manifest-variables"], 

526 help_description="Plugin provided manifest variables (such as `{{path:FOO}}`)", 

527 argparser=add_arg( 

528 "manifest_variable", 

529 metavar="manifest-variable", 

530 help="Name of the variable (such as `path:FOO` or `{{path:FOO}}`) to display details about", 

531 ), 

532) 

533def _plugin_cmd_show_manifest_variables(context: CommandContext) -> None: 

534 plugin_feature_set = context.load_plugins() 

535 variables = plugin_feature_set.manifest_variables 

536 substitution = context.substitution 

537 parsed_args = context.parsed_args 

538 variable_name = parsed_args.manifest_variable 

539 fo = _output_styling(context.parsed_args, sys.stdout) 

540 if variable_name.startswith("{{") and variable_name.endswith("}}"): 

541 variable_name = variable_name[2:-2] 

542 variable: Optional[PluginProvidedManifestVariable] 

543 if variable_name.startswith("env:") and len(variable_name) > 4: 

544 env_var = variable_name[4:] 

545 variable = PluginProvidedManifestVariable( 

546 plugin_feature_set.plugin_data["debputy"], 

547 variable_name, 

548 variable_value=None, 

549 is_context_specific_variable=False, 

550 is_documentation_placeholder=True, 

551 variable_reference_documentation=f'Environment variable "{env_var}"', 

552 ) 

553 else: 

554 variable = variables.get(variable_name) 

555 if variable is None: 

556 _error( 

557 f'Cannot resolve "{variable_name}" as a known variable from any of the available' 

558 f" plugins. Please use `debputy plugin list manifest-variables` to list all known" 

559 f" provided variables." 

560 ) 

561 

562 var_with_braces = "{{" + variable_name + "}}" 

563 try: 

564 source_value = substitution.substitute(var_with_braces, "CLI request") 

565 except DebputySubstitutionError: 

566 source_value = None 

567 binary_value = source_value 

568 print(f"Variable: {variable_name}") 

569 fo.print_visual_formatting(f"=========={'=' * len(variable_name)}") 

570 print() 

571 

572 if variable.is_context_specific_variable: 

573 try: 

574 binary_value = substitution.with_extra_substitutions( 

575 PACKAGE="<package-name>", 

576 ).substitute(var_with_braces, "CLI request") 

577 except DebputySubstitutionError: 

578 binary_value = None 

579 

580 doc = variable.variable_reference_documentation or "No documentation provided" 

581 _render_multiline_documentation(doc) 

582 

583 if source_value == binary_value: 

584 print(f"Resolved: {_render_manifest_variable_value(source_value)}") 

585 else: 

586 print("Resolved:") 

587 print(f" [source context]: {_render_manifest_variable_value(source_value)}") 

588 print(f" [binary context]: {_render_manifest_variable_value(binary_value)}") 

589 

590 if variable.is_for_special_case: 

591 print( 

592 'Special-case: The variable has been marked as a "special-case"-only variable.' 

593 ) 

594 

595 if not variable.is_documentation_placeholder: 

596 print(f"Plugin: {variable.plugin_metadata.plugin_name}") 

597 

598 if variable.is_internal: 

599 print() 

600 # I knew everything I felt was showing on my face, and I hate that. I grated out, 

601 print("That was private.") 

602 

603 

604def _determine_ppf( 

605 context: CommandContext, 

606) -> Tuple[PackagerProvidedFileClassSpec, bool]: 

607 feature_set = context.load_plugins() 

608 ppf_name = context.parsed_args.ppf_name 

609 try: 

610 return feature_set.packager_provided_files[ppf_name], False 

611 except KeyError: 

612 pass 

613 

614 orig_ppf_name = ppf_name 

615 if ( 

616 ppf_name.startswith("d/") 

617 and not os.path.lexists(ppf_name) 

618 and os.path.lexists("debian/" + ppf_name[2:]) 

619 ): 

620 ppf_name = "debian/" + ppf_name[2:] 

621 

622 if ppf_name in ("debian/control", "debian/debputy.manifest", "debian/rules"): 

623 if ppf_name == "debian/debputy.manifest": 

624 doc = f"{DEBPUTY_DOC_ROOT_DIR}/MANIFEST-FORMAT.md" 

625 else: 

626 doc = "Debian Policy Manual or a packaging tutorial" 

627 _error( 

628 f"Sorry. While {orig_ppf_name} is a well-defined packaging file, it does not match the definition of" 

629 f" a packager provided file. Please see {doc} for more information about this file" 

630 ) 

631 

632 if context.has_dctrl_file and os.path.lexists(ppf_name): 

633 basename = ppf_name[7:] 

634 if "/" not in basename: 

635 debian_dir = build_virtual_fs([basename]) 

636 all_ppfs = detect_all_packager_provided_files( 

637 feature_set.packager_provided_files, 

638 debian_dir, 

639 context.binary_packages(), 

640 ) 

641 if all_ppfs: 

642 matched = next(iter(all_ppfs.values())) 

643 if len(matched.auto_installable) == 1 and not matched.reserved_only: 

644 return matched.auto_installable[0].definition, True 

645 if not matched.auto_installable and len(matched.reserved_only) == 1: 

646 reserved = next(iter(matched.reserved_only.values())) 

647 if len(reserved) == 1: 

648 return reserved[0].definition, True 

649 

650 _error( 

651 f'Unknown packager provided file "{orig_ppf_name}". Please use' 

652 f" `debputy plugin list packager-provided-files` to see them all." 

653 ) 

654 

655 

656@plugin_show_cmds.register_subcommand( 

657 ["packager-provided-files", "ppf", "p-p-f"], 

658 help_description="Show details about a given packager provided file (debian/pkg.foo)", 

659 argparser=add_arg( 

660 "ppf_name", 

661 metavar="name", 

662 help="Name of the packager provided file (such as `changelog`) to display details about", 

663 ), 

664) 

665def _plugin_cmd_show_ppf(context: CommandContext) -> None: 

666 ppf, matched_file = _determine_ppf(context) 

667 

668 fo = _output_styling(context.parsed_args, sys.stdout) 

669 

670 fo.print(f"Packager Provided File: {ppf.stem}") 

671 fo.print_visual_formatting(f"========================{'=' * len(ppf.stem)}") 

672 fo.print() 

673 ref_doc = ppf.reference_documentation 

674 description = ref_doc.description if ref_doc else None 

675 doc_uris = ref_doc.format_documentation_uris if ref_doc else tuple() 

676 if description is None: 

677 fo.print( 

678 f"Sorry, no description provided by the plugin {ppf.debputy_plugin_metadata.plugin_name}." 

679 ) 

680 else: 

681 for line in description.splitlines(keepends=False): 

682 fo.print(line) 

683 

684 fo.print() 

685 fo.print("Features:") 

686 if ppf.packageless_is_fallback_for_all_packages: 

687 fo.print(f" * debian/{ppf.stem} is used for *ALL* packages") 

688 else: 

689 fo.print(f' * debian/{ppf.stem} is used for only for the "main" package') 

690 if ppf.allow_name_segment: 

691 fo.print(" * Supports naming segment (multiple files and custom naming).") 

692 else: 

693 fo.print( 

694 " * No naming support; at most one per package and it is named after the package." 

695 ) 

696 if ppf.allow_architecture_segment: 

697 fo.print(" * Supports architecture specific variants.") 

698 else: 

699 fo.print(" * No architecture specific variants.") 

700 if ppf.supports_priority: 

701 fo.print( 

702 f" * Has a priority system (default priority: {ppf.default_priority})." 

703 ) 

704 

705 fo.print() 

706 fo.print("Examples matches:") 

707 

708 if context.has_dctrl_file: 

709 first_pkg = next(iter(context.binary_packages())) 

710 else: 

711 first_pkg = "example-package" 

712 example_files = [ 

713 (f"debian/{ppf.stem}", first_pkg), 

714 (f"debian/{first_pkg}.{ppf.stem}", first_pkg), 

715 ] 

716 if ppf.allow_name_segment: 

717 example_files.append( 

718 (f"debian/{first_pkg}.my.custom.name.{ppf.stem}", "my.custom.name") 

719 ) 

720 if ppf.allow_architecture_segment: 

721 example_files.append((f"debian/{first_pkg}.{ppf.stem}.amd64", first_pkg)), 

722 if ppf.allow_name_segment: 

723 example_files.append( 

724 ( 

725 f"debian/{first_pkg}.my.custom.name.{ppf.stem}.amd64", 

726 "my.custom.name", 

727 ) 

728 ) 

729 fs_root = build_virtual_fs([x for x, _ in example_files]) 

730 priority = ppf.default_priority if ppf.supports_priority else None 

731 rendered_examples = [] 

732 for example_file, assigned_name in example_files: 

733 example_path = fs_root.lookup(example_file) 

734 assert example_path is not None and example_path.is_file 

735 dest = ppf.compute_dest( 

736 assigned_name, 

737 owning_package=first_pkg, 

738 assigned_priority=priority, 

739 path=example_path, 

740 ) 

741 dest_path = "/".join(dest).lstrip(".") 

742 rendered_examples.append((example_file, dest_path)) 

743 

744 fo.print_list_table(["Source file", "Installed As"], rendered_examples) 

745 

746 if doc_uris: 

747 fo.print() 

748 fo.print("Documentation URIs:") 

749 for uri in doc_uris: 

750 fo.print(f" * {fo.render_url(uri)}") 

751 

752 plugin_name = ppf.debputy_plugin_metadata.plugin_name 

753 fo.print() 

754 fo.print(f"Install Mode: 0{oct(ppf.default_mode)[2:]}") 

755 fo.print(f"Provided by plugin: {plugin_name}") 

756 if ( 

757 matched_file 

758 and plugin_name != "debputy" 

759 and plugin_name not in context.requested_plugins() 

760 ): 

761 fo.print() 

762 _warn( 

763 f"The file might *NOT* be used due to missing Build-Depends on debputy-plugin-{plugin_name}" 

764 ) 

765 

766 

767@plugin_show_cmds.register_subcommand( 

768 ["pluggable-manifest-rules", "p-m-r", "pmr"], 

769 help_description="Pluggable manifest rules (such as install rules)", 

770 argparser=add_arg( 

771 "pmr_rule_name", 

772 metavar="rule-name", 

773 help="Name of the rule (such as `install`) to display details about", 

774 ), 

775) 

776def _plugin_cmd_show_manifest_rule(context: CommandContext) -> None: 

777 feature_set = context.load_plugins() 

778 parsed_args = context.parsed_args 

779 req_rule_type = None 

780 rule_name = parsed_args.pmr_rule_name 

781 if "::" in rule_name and rule_name != "::": 

782 req_rule_type, rule_name = rule_name.split("::", 1) 

783 

784 matched = [] 

785 

786 base_type = Iterable[Tuple[Union[str, Type[Any]], DispatchingParserBase[Any]]] 

787 parser_generator = feature_set.manifest_parser_generator 

788 table_parsers: base_type = parser_generator.dispatchable_table_parsers.items() 

789 object_parsers: base_type = parser_generator.dispatchable_object_parsers.items() 

790 

791 parsers = chain( 

792 table_parsers, 

793 object_parsers, 

794 ) 

795 

796 for rule_type, dispatching_parser in parsers: 

797 if req_rule_type is not None and req_rule_type not in _parser_type_name( 

798 rule_type 

799 ): 

800 continue 

801 if dispatching_parser.is_known_keyword(rule_name): 

802 matched.append((rule_type, dispatching_parser)) 

803 

804 if len(matched) != 1 and (matched or rule_name != "::"): 

805 if not matched: 

806 _error( 

807 f"Could not find any pluggable manifest rule related to {parsed_args.pmr_rule_name}." 

808 f" Please use `debputy plugin list pluggable-manifest-rules` to see the list of rules." 

809 ) 

810 match_a = matched[0][0] 

811 match_b = matched[1][0] 

812 _error( 

813 f"The name {rule_name} was ambiguous and matched multiple rule types. Please use" 

814 f" <rule-type>::{rule_name} to clarify which rule to use" 

815 f" (such as {_parser_type_name(match_a)}::{rule_name} or {_parser_type_name(match_b)}::{rule_name})." 

816 f" Please use `debputy plugin list pluggable-manifest-rules` to see the list of rules." 

817 ) 

818 

819 if matched: 

820 rule_type, matched_dispatching_parser = matched[0] 

821 plugin_provided_parser = matched_dispatching_parser.parser_for(rule_name) 

822 if isinstance(rule_type, str): 

823 manifest_attribute_path = rule_type 

824 else: 

825 manifest_attribute_path = SUPPORTED_DISPATCHABLE_TABLE_PARSERS[rule_type] 

826 parser_type_name = _parser_type_name(rule_type) 

827 parser = plugin_provided_parser.parser 

828 plugin_metadata = plugin_provided_parser.plugin_metadata 

829 else: 

830 rule_name = "::" 

831 parser = parser_generator.dispatchable_object_parsers[OPARSER_MANIFEST_ROOT] 

832 parser_type_name = "" 

833 plugin_metadata = plugin_metadata_for_debputys_own_plugin() 

834 manifest_attribute_path = "" 

835 

836 is_root_rule = rule_name == "::" 

837 print( 

838 render_rule( 

839 rule_name, 

840 parser, 

841 plugin_metadata, 

842 is_root_rule=is_root_rule, 

843 ) 

844 ) 

845 

846 if not is_root_rule: 

847 print( 

848 f"Used in: {manifest_attribute_path if manifest_attribute_path != '<ROOT>' else 'The manifest root'}" 

849 ) 

850 print(f"Rule reference: {parser_type_name}::{rule_name}") 

851 print(f"Plugin: {plugin_metadata.plugin_name}") 

852 else: 

853 print(f"Rule reference: {rule_name}") 

854 

855 print() 

856 print( 

857 "PS: If you want to know more about a non-trivial type of an attribute such as `FileSystemMatchRule`," 

858 ) 

859 print( 

860 "you can use `debputy plugin show type-mappings FileSystemMatchRule` to look it up " 

861 ) 

862 

863 

864def _render_discard_rule_example( 

865 fo: OutputStylingBase, 

866 discard_rule: PluginProvidedDiscardRule, 

867 example: AutomaticDiscardRuleExample, 

868) -> None: 

869 processed = process_discard_rule_example(discard_rule, example) 

870 

871 if processed.inconsistent_paths: 

872 plugin_name = discard_rule.plugin_metadata.plugin_name 

873 _warn( 

874 f"This example is inconsistent with what the code actually does."