Improve --help for enhanced user experience (#24903)

Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
This commit is contained in:
Harry Mellor
2025-09-24 23:08:18 +00:00
committed by GitHub
parent 1f29141258
commit e7f27ea648
8 changed files with 114 additions and 137 deletions
+79 -8
View File
@@ -1720,6 +1720,7 @@ class FlexibleArgumentParser(ArgumentParser):
"Additionally, list elements can be passed individually using +:\n"
' --json-arg \'{"key4": ["value3", "value4", "value5"]}\'\n'
" --json-arg.key4+ value3 --json-arg.key4+=\'value4,value5\'\n\n")
_search_keyword: Optional[str] = None
def __init__(self, *args, **kwargs):
# Set the default "formatter_class" to SortedHelpFormatter
@@ -1768,13 +1769,79 @@ class FlexibleArgumentParser(ArgumentParser):
self._action_groups.append(group)
return group
def format_help(self) -> str:
# Add tip about JSON arguments to the epilog
epilog = self.epilog or ""
if (self.add_json_tip
and not epilog.startswith(FlexibleArgumentParser._json_tip)):
self.epilog = FlexibleArgumentParser._json_tip + epilog
return super().format_help()
def format_help(self):
# Only use custom help formatting for bottom level parsers
if self._subparsers is not None:
return super().format_help()
formatter = self._get_formatter()
# Handle keyword search of the args
if (search_keyword := self._search_keyword) is not None:
# Normalise the search keyword
search_keyword = search_keyword.lower().replace("_", "-")
# Return full help if searching for 'all'
if search_keyword == 'all':
self.epilog = self._json_tip
return super().format_help()
# Return group help if searching for a group title
for group in self._action_groups:
if group.title and group.title.lower() == search_keyword:
formatter.start_section(group.title)
formatter.add_text(group.description)
formatter.add_arguments(group._group_actions)
formatter.end_section()
formatter.add_text(self._json_tip)
return formatter.format_help()
# Return matched args if searching for an arg name
matched_actions = []
for group in self._action_groups:
for action in group._group_actions:
# search option name
if any(search_keyword in opt.lower()
for opt in action.option_strings):
matched_actions.append(action)
if matched_actions:
formatter.start_section(
f"Arguments matching '{search_keyword}'")
formatter.add_arguments(matched_actions)
formatter.end_section()
formatter.add_text(self._json_tip)
return formatter.format_help()
# No match found
formatter.add_text(
f"No group or arguments matching '{search_keyword}'.\n"
"Use '--help' to see available groups or "
"'--help=all' to see all available parameters.")
return formatter.format_help()
# usage
formatter.add_usage(self.usage, self._actions,
self._mutually_exclusive_groups)
# description
formatter.add_text(self.description)
# positionals, optionals and user-defined groups
formatter.start_section("Config Groups")
config_groups = ""
for group in self._action_groups:
if not group._group_actions:
continue
title = group.title
description = group.description or ""
config_groups += f"{title: <24}{description}\n"
formatter.add_text(config_groups)
formatter.end_section()
# epilog
formatter.add_text(self.epilog)
# determine help from format above
return formatter.format_help()
def parse_args( # type: ignore[override]
self,
@@ -1807,7 +1874,11 @@ class FlexibleArgumentParser(ArgumentParser):
# Convert underscores to dashes and vice versa in argument names
processed_args = list[str]()
for i, arg in enumerate(args):
if arg.startswith('--'):
if arg.startswith("--help="):
FlexibleArgumentParser._search_keyword = arg.split(
'=', 1)[-1].lower()
processed_args.append("--help")
elif arg.startswith('--'):
if '=' in arg:
key, value = arg.split('=', 1)
key = pattern.sub(repl, key, count=1)