Add help parameter to arguments#3473
Conversation
yurishevtsov
force-pushed
the
add-help-kwarg-to-arg-params
branch
4 times, most recently
from
73e3c13 to
b145f91
Compare
Refactor: pull out args formatter into a dedicated method
yurishevtsov
force-pushed
the
add-help-kwarg-to-arg-params
branch
from
b145f91 to
71240f8
Compare
|
That feature exists in Cloup since v0.1.40: https://github.com/janluke/cloup/releases/tag/v0.14.0 . So additional review from @janluke would be great! :) |
kdeldycke
left a comment
kdeldycke
left a comment
There was a problem hiding this comment.
Good PR that mirrors the way help is managed on Option.
| Unreleased | ||
|
|
||
| - :class:`Argument` accepts a ``help`` parameter, and help output includes | ||
| an ``Arguments`` section when argument help is available. :issue:`2983` |
There was a problem hiding this comment.
| an ``Arguments`` section when argument help is available. :issue:`2983` | |
| an ``Arguments`` section when argument help is available. :issue:`2983` :pr:`3473` |
|
|
||
| if deprecated: | ||
| label = _format_deprecated_label(deprecated) | ||
| help = f"{help} {label}" if help is not None else label |
There was a problem hiding this comment.
Can you extend the test_deprecated_usage test so we cover the look and shape of the deprecation message for the argument?
| formatter.write_dl(opts) | ||
|
|
||
| def format_args(self, ctx: Context, formatter: HelpFormatter) -> None: | ||
| """Writes all the arguments into the formatter if they exist.""" |
There was a problem hiding this comment.
Maybe update that docstring as that method only write arguments that produce a help record.
|
|
||
| super().__init__(param_decls, required=required, **attrs) | ||
|
|
||
| def to_info_dict(self) -> dict[str, t.Any]: |
There was a problem hiding this comment.
Can you add a test that cover this new public method?
There was a problem hiding this comment.
And also use that oportunity to check the behavior with None, empty help, and multi-line help. With single and multiple arguments. And with nargs=-1 arguments.
| with formatter.section(_("Options")): | ||
| formatter.write_dl(opts) | ||
|
|
||
| def format_args(self, ctx: Context, formatter: HelpFormatter) -> None: |
There was a problem hiding this comment.
Should we name that format_arguments to align it with the other format_options, format_epilog and format_usage which use long names?
| {class}`click.argument` does not take a `help` parameter. This follows the Unix Command Line Tools convention of using arguments only for necessary things and documenting them in the command help text | ||
| by name. This should then be done via the docstring. | ||
| {class}`click.argument` accepts an optional `help` parameter that is shown in | ||
| the ``Arguments`` section of the help page. You can still document arguments |
There was a problem hiding this comment.
A detailed I noticed: Cloup use Positional arguments for its section name while this use Arguments.
Not sure which is strictly right. @janluke any opinion?
3 participants
Adds a
helpparameter toclick.argument()and an Arguments section on--helpwhen argument help is set. Commands without argument help are unchanged.Implementation follows options:
Argument.get_help_record()returns the metavar and help text for the help formatter (the baseParameterclass returnsNone, so arguments never appeared in help tables before).Argument.to_info_dict()now includeshelp, matchingOption, so parameter metadata stays consistent for doc tools; this is not required for CLI help output.Deprecated arguments without explicit
helpshow a deprecation-only row in Arguments, matching deprecated options.fixes #2983