Migrating to typer and docstring with --help

[alanwilter]

I'm adapting my codes to use typer, I really like it. But I also like proper docstrings and then when I did this:

@app.command() def main( database: str = typer.Argument(..., help="Path to the database file."), graders: bool = typer.Option(False, "-g", "--graders", help="Analyse data for Graders"), annotators: bool = typer.Option(False, "-a", "--annotators", help="Analyse data for Annotators"), computer: bool = typer.Option(False, "-m", "--computer", help="Analyse data for MediaPipe"), precision: int = typer.Option(2, "-p", "--precision", help="Decimal precision for output numbers"), csv_out: str = typer.Option("mae_results.csv", "-c", "--csv-out", help="Output CSV filename"), ) -> None: """Pipeline script to calculate Mean Absolute Error (MAE).   For the data measurements done via Graders, Annotators and Computer.   Example:  $ face-eval -d face_2024-09-06.db -gam   Args:  database (str): Path to the database file.  graders (bool): Analyse data for Graders.  annotators (bool): Analyse data for Annotators.  computer (bool): Analyse data for MediaPipe.  precision (int): Decimal precision for output numbers.  csv_out (str): Output CSV filename.  """ ...

I noticed that when I do, I get:

$ face-eval -h Usage: face-eval [OPTIONS] DATABASE Pipeline script to calculate Mean Absolute Error (MAE). For the data measurements done via Graders, Annotators and Computer. Example: $ face-eval -d face_2024-09-06.db -gam Args: database (str): Path to the database file. graders (bool): Analyse data for Graders. annotators (bool): Analyse data for Annotators. computer (bool): Analyse data for MediaPipe. precision (int): Decimal precision for output numbers. csv_out (str): Output CSV filename. ...

Not great :-(

So, what is the best practice here? Give up the detailed docstring and format for those cases?

Or there is a way to properly format the help output when using --help?

As I use Ruff, I may have Missing argument description in the docstring (D417) and I like this to keep my functions well documented.

Operating System

Linux, Mac

Typer Version

0.12.5

Python Version

3.10.14

[YuriiMotov]

Printed well with app = typer.Typer(rich_markup_mode="rich").

Interestingly, I have Rich installed and by default rich_markup_mode should be rich (and it is), but it only works if I specify it explicitly

import typer # app = typer.Typer() app = typer.Typer(rich_markup_mode="rich") @app.command() def main() -> None: """Pipeline script to calculate Mean Absolute Error (MAE).   For the data measurements done via Graders, Annotators and Computer.   Example:  $ face-eval -d face_2024-09-06.db -gam   Args:  database (str): Path to the database file.  graders (bool): Analyse data for Graders.  annotators (bool): Analyse data for Annotators.  computer (bool): Analyse data for MediaPipe.  precision (int): Decimal precision for output numbers.  csv_out (str): Output CSV filename.  """ if __name__ == "__main__": app()

[svlandeg]

@alanwilter: thanks for the report and apologies for the late follow-up!

Yurii is right - this should have worked out of the box by using Rich by default if you have it installed. There's a small bug that was interfering with this behaviour though. Should be fixed once #1304 is merged & released.

TLDR: if you use app = typer.Typer(rich_markup_mode="rich") for now, it should print correctly. Once the PR 1304 is merged and released, and if you have rich installed, then simply app = typer.Typer() should work correctly as well.

[alanwilter]

Many thanks, I can confirm that app = typer.Typer(rich_markup_mode="rich") did the trick. Just wondering now why #1304 is not merged and released.

[svlandeg]

Oh, it will be. It's basically waiting on a final review by Tiangolo and while that might not look like a lot of work, his TODO list is pretty huge 🥲 But it's on his internal board and he'll get to it!