Best practices for managing Typer objects and callers at scale?

[manoelpqueiroz]

First Check

• I added a very descriptive title here.
• I used the GitHub search to find a similar question 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 tutorials 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

from typing_extensions import Annotated

import typer
from rich import print

from my_python_project import __version__

app = typer.Typer(no_args_is_help=True)

def version_callback(print_version: bool = False) -> None:
    if print_version:
        print(f":package: [yellow]Python Project[/] [bold green]{__version__}[/]")

        raise typer.Exit()

@app.callback()
def main(
    version: Annotated[
        bool,
        typer.Option(
            "-v",
            "--version",
            help="Print the current version of this program and exit.",
            callback=version_callback
        )
    ] = False
):
    """A handy CLI program.

    See usage below for commands and options.
    """
    pass

Description

Hi guys, I have been tinkering with Typer more recently and I would like to take the cleaniness that the library brings to the table to the next level.

Using type annotations is one of the key strengths of Typer, and like the example, which implements a main caller and an option to display the version, it's simple, doesn't need boilerplate and gets the job done.

And while the documentation provides a great suggestion to better organize complex programs, I've been wondering what are some other best practices when scaling the usage of Typer? 🤔

More specifically, declaring the typer.Option within the Annotated object within the main function seems to be just one example of many in which function calls can become giant and verbose. Are there any suggestions on how to tackle simplifying and perhaps creating these objects elsewhere to later import and use in these definitions?

This is more of a discussion about better usage of Typer and proper project structure to ensure things don't get out of control. I personally tend to think of storing the help messages for options in a single place should they need more text do be properly explained, but is this really the best way to do it? Shouldn't one store the actual whole typer.Option object instead? Where? Or perhaps there is a completely different way to approach this, so many possibilities!

I'd like your thoughts on this, especially if you have dealt with Typer on a larger scale. Knowing the better ways to apply the tool in both small and large scales would be great for my future projects!

Operating System

Linux

Operating System Details

No response

Typer Version

0.15.1

Python Version

3.13.1

Additional Context

No response

[Arashkazemii]

You can reuse Annotated aliases for shared option metadata, while keeping the default on each command parameter:

from typing import Annotated
import typer

app = typer.Typer()

def show_version(value: bool):
    if value:
        typer.echo("1.0")
        raise typer.Exit()

VersionOption = Annotated[
    bool,
    typer.Option("--version", callback=show_version, is_eager=True),
]

@app.command()
def run(version: VersionOption = False):
    typer.echo("running")

if __name__ == "__main__":
    app()

Put genuinely shared aliases/callbacks in an options.py module. For groups of related commands, each module can expose a small Typer() app, and the root app can compose them with add_typer(..., name="...").

Keep command functions as adapters: accept CLI values, construct a configuration object if useful, then call ordinary service functions. Those services should not depend on Typer's OptionInfo objects or invoke the CLI. This also makes them callable from tests or another interface.

Some explicit signature repetition is useful because Typer inspects that signature to build help and parse inputs. I would avoid hiding all options in an arbitrary wrapper or replacing the command signature with **kwargs. Use aliases for repeated metadata and sub-apps for organization, rather than one large dynamically generated command.