Skip to content

Specifying help for arguments & options in function docstrings #336

Open
@alexreg

Description

@alexreg

First Check

  • I added a very descriptive title to this issue.
  • I used the GitHub search to find a similar issue and didn't find it.
  • I searched the Typer documentation, with the integrated search.
  • I already searched in Google "How to X in Typer" and didn't find any information.
  • I already read and followed all the tutorial in the docs and didn't find an answer.
  • I already checked if it is not related to Typer but to Click.

Commit to Help

  • I commit to help with one of those options 👆

Example Code

This is the current way to add help text for arguments (and similarly for options).

import typer


def main(name: str = typer.Argument(..., help="The name of the user to greet")):
    """
    Say hi to NAME very gently, like Dirk.
    """
    typer.echo(f"Hello {name}")


if __name__ == "__main__":
    typer.run(main)

Description

It would be convenient to be able to specify help text for arguments and options via the function's docstring in addition to the current method. At the moment, of course, help can only be specified for the command itself via the function's docstring.

Wanted Solution

To be able to specify help text for command arguments and options via the function docstring, as below.

Wanted Code

This should behave in a totally equivalent way to the above example of code that already works.

import typer


def main(name: str = typer.Argument(...)):
    """
    Say hi to NAME very gently, like Dirk.

    :param name: The name of the user to greet
    """
    typer.echo(f"Hello {name}")


if __name__ == "__main__":
    typer.run(main)

Note, the other standard syntax for parameter descriptions in functions is @param name: The name of the user to greet, and this should also be supported, I would think.

Alternatives

Just use the current method of specifying help text in the function signature, via arg = typer.Argument(..., help="<text>") or opt = typer.Option(..., help="<text>"). I argue that a) this can be seen as "polluting" the function signature and making it harder to read quickly/easily, b) it is most consistent to be able to specify help text for a command and its arguments 100% through docstrings (if so desired).

Operating System

macOS

Operating System Details

No response

Typer Version

0.4.0

Python Version

3.9.6

Additional Context

No response

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions