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!