Conversation
Resolve help intent before argument binding so --help renders the same help as the positional help subcommand on every command surface (provider, service, operation, custom/nested commands). New argparser helpers detect and strip the exact --help token; each of the four dispatch layers routes to its existing create_help_command(). --help mirrors the positional help token's position semantics, and is added to _NO_AUTO_PROMPT_ARGS so a help request bypasses auto-prompt. The positional help subcommand is unchanged.
Functional coverage of --help on every surface, including value and optional-value options before --help, and --help appearing before a command or operation token (help resolves at the depth reached, later tokens ignored). Unit coverage for the argparser helpers: - only the exact --help token counts as help - an option's value is not mistaken for a command when routing to top-level help - parsing the tokens before --help still lets --version and Ctrl-C through - descending into a subcommand is decided by parsing rather than string position Updates the structured-error fixture for the extended HELP_BLURB.
kdaily
changed the title
| # append the ``help`` positional argument, so a trailing command is | ||
| # ignored. | ||
| head = self._tokens_before_help(args) | ||
| return head + ['help'] |
There was a problem hiding this comment.
Could we avoid converting the help request into a positional help token here? The parse fails because --query has no value, so this rewrites argv to ... --query help, which strips the help intent and lets the command run. Worried about destructive operations like aws s3api delete-object --bucket b --key k --query --help when the intent is --help
There was a problem hiding this comment.
Worth a regression test on a mutating operation specifically
There was a problem hiding this comment.
Agreed. Supplying --help should never behave as supplying help as a value to another parameter.
|
|
||
| def first_help_option_index(args): | ||
| """Return the index of the first ``--help`` token, or ``None`` if absent.""" | ||
| for index, arg in enumerate(args): |
There was a problem hiding this comment.
Help detection should stop at the -- end-of-options marker. aws configure set test.key -- --help normally treats --help as the positional value, but this interprets it as a help request and renders command help instead
There was a problem hiding this comment.
Agreed, it should behave as other parameters in this aspect. I'll publish a revision
| # that exceptions can be raised, which should have the same | ||
| # general exception handling logic as calling into the | ||
| # command table. This is why it's in the try/except clause. | ||
| parsed_args, remaining = parser.parse_known_args(args) |
There was a problem hiding this comment.
Could help get consumed as the preceding option’s value here? For example:
aws ec2 terminate-instances --instance-ids i-abc123 --query --help
Currently on v2 this fails because --query has no value. With this change it effectively becomes --query help and calls TerminateInstances.
My read is help can be a query value, but --help is an explicit option.
Could we preserve that distinction instead of reinserting it as a normal
There was a problem hiding this comment.
I agree. It should behave more like other parameters. I'll revise.
There was a problem hiding this comment.
I think this would mean that we need to enter help directly (calling the help command)?
|
I am taking over ownership of implementing this feature. Closing in favor of #10657. |
3 participants
Issue #, if available:
helpcommand conventions (-h/--helporaws help <command/service>#303Description of changes:
Adds a
--helpparameter that renders the same help as the existinghelpsubcommand, on every command: the top-levelaws, a service (aws ec2 --help), an operation (aws ec2 describe-instances --help), and custom/nested commands (aws configure get --help). Thehelpsubcommand is unchanged.Implementation
Help intent is resolved before normal argument binding.
awscli/argparser.pydetect and strip the exact--helptoken (is_help_option_present,strip_help_options,first_help_option_index).CLIDriver.main,ServiceCommand,ServiceOperation,BasicCommand) routes to its existingcreate_help_command()with--helpstripped. Detecting it up front means a preceding value option cannot consume it.--helpis added to_NO_AUTO_PROMPT_ARGSso a help request bypasses auto-prompt.Behavior
helpsubcommand. Help resolves at the depth reached when--helpappears, and tokens (sub-commands or parameters) after it are ignored, soaws ec2 --help describe-instancesrenders EC2 service help. This is the same asaws ec2 help describe-instances.--helpis help.--hel,--he, and--help=xare not; they fall through as unknown options. This avoids colliding with operation parameters with a shared prefix, like--health-check-type.aws --region ec2 --helprenders top-level help, becauseec2is--region's value.Known limitation
--helpis deliberately absent from the generated global-options synopsis and reference pages. Those are generated fromcli.jsonand pinned bytests/functional/test_globals.py;--helpis intentionally not acli.jsonoption, since that would re-enable prefix matching so--helresolves again. Users find--helpthrough the error text shown on a bad invocation and each command's own help output.Testing
--helpon every command type, including value and optional-value options before--help, and--helpbefore a command/operation token.argparserhelpers, exact-token-only detection, value-aware routing, the pre-help-slice parse, and subcommand-vs-help positioning.By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.