[FEATURE] Support help strings for CLI arguments

[tiangolo]

Is your feature request related to a problem

Not necessarily.

Currently, Typer doesn't generate any or receive any automatic help text for CLI arguments, following the same ideas from Click, assuming it is provided in the main help text in the docstring.

But in reality, it's difficult to keep consistency for CLI arguments when it has to be done by hand. For example, deciding if using lowercase or uppercase, declaring types, the format to declare types for CLI arguments, etc.

The solution you would like

I would like to have a help parameter in typer.Argument(help="Some description of this specific arg").

Then generate some basic documentation for the CLI Argument, including type, etc.

It could be a bit less pretty than very carefully crafted manual descriptions in a docstring, but would be a lot easier to use and maintain, more in line with how the rest of Typer works, easy, consistent, and robust/"professional" by default.

I would expect that in the long term, that feature would enable better CLIs with more consistent information, even more than the restriction of asking developers to manually document CLI arguments and keep consistency by hand with their own methods.

Describe alternatives you've considered

To leave it as is, to keep in line with Click. Which is something I've tried with Typer.

But I think this is one of the cases where it is worth adding a bit extra to keep in line with the same ideas from Typer, as was the re-implementation of the shell completion system to effectively support all the shells.

Additional context

⌨️ ✨ 🤷

[juped]

@IamCathal and @csr will be working on this!

[csr]

Glad to be working on Typer with Cathal!

I've gone through most of the user guide and I found everything to be well documented. From my understanding, Typer currently follows Click's footsteps by having developers optionally specify some help text with docstrings.

My intuition is that we'll need this feature to be optional for backward compatibility (at least for the short term), and perhaps we could take inspiration from the CLI options help parameter implementation (ie typer.Option(False, help="Say hi formally.")). @tiangolo Do you think it would be a good idea to look closely at that implementation for CLI options and use it as a guideline to implement this feature? Anything we must pay special attention to? EDIT: we saw the Option help string feature was most likely part of Click, then we're trying to figure out how to implement it natively in Typer.

Since CLI arguments could have an optional value assigned to them, should we also support the optional show_default parameter to display the argument default value in the help text?

For the help text, I think we'll also need to define formally what kind of output we want for the arguments, and decide if we only want to show the help text for the arguments that have a help text? e.g. (should the argument name be uppercased?)

Arguments:
    NAME TEXT        Your first name. [default: Wade]
    LASTNAME TEXT    Your last name. [default: Wilson]

I also see we may need to write tests for this feature, and update the documentation to showcase it. Perhaps these could go into a different PR or they in this one here?

Apologies for the many questions, that's just me thinking out loud :)

[tiangolo]

Awesome to have you here!

Thanks for all the questions, great thought process 🤓

First, yes, it would probably work like you say, with a typer.Argument(..., help="Some description").

Yep, I think having the show_default would make sense.

For the help text, I was thinking that it would make sense to support a way to omit showing the help text, in the same style of Click, but default it to showing it. I thought that because if some arguments have a help text but others don't, then those will show up in the help text, but the others won't, which would be a bit inconsistent and could end up making it look like those arguments are not available.

I was thinking that the parameter help could default to a new placeholder object (like Default) to say that it will be autogenerated, but that can be set to None to disable generating the help for that argument.

---

Now, on the other side, I was checking the code and I was realizing that this could actually be quite more complex than what I was originally thinking 😅

It would actually probably involve creating a new subclass of Click's Argument that takes a help parameter. And then a sub-class of Click's Command to create a new class method format_arguments() (that currently doesn't exist) similar to format_options() to later be used in an extended method format_help() to use it and generate the new help text.

And then, in the Typer side itself, it would be just to take the help parameter from typer.Argument() and passing it to the new class, as you say.

The thing is, the implementation is quite involved and complex and touches several places inside of Click. So it might be actually difficult to implement as a first PR (now I think it's probably one of the most complex features to implement right now 😅 ).

[tiangolo]

This was implemented in #123 , available in version 0.3.0 🚀

So I can close this now. 🎉