One file per command without globals

[ckutlu]

Hi there! I recently started using typer extensively and so far very happy with all the bells and whistles it provides. Great work!

Oftentimes I often write small CLI tools to make my life easier and use subcommands to provide categories of things that go well together. I started having a pattern for having one file per command in my projects that deviates a bit from the recommended way of doing it in the documentation (here). It began from my desire to avoid having typer app created at the top-level in modules mainly becase I may want to pass an argument to typer.Typer(...) and I may not want that argument to live in the global scope.

This is how my folder structure looks like:

src/mytool/_cli
├── __init__.py
└── mytool
    ├── __init__.py
    ├── subcommand1.py
    ├── subcommand2.py
    ...

Contents of __init__.py:

from typing import Protocol

import typer

from . import subcommand1, subcommand2


class AppModuleProtocol(Protocol):
    """A protocol for modules to follow for implementing typer CLI subcommands
    as independent Typer apps."""

    @property
    def __app_name__(self) -> str: ...

    def __create__(self) -> typer.Typer:
        """Create a Typer app from `self` and return it."""
        ...


__all__ = ["__create__"]


__app_name__ = "mytool"


_ALL_SUBAPPS: list[AppModuleProtocol] = [subcommand1, subcommand2]


def __create__() -> typer.Typer:
    main_app = typer.Typer(name=__app_name__)
    for subapp in _ALL_SUBAPPS:
        main_app.add_typer(subapp.__create__())

    return main_app

This tells me that every subcommand file I add should have a create function defined with the given signature. The type checking tool I use even flags where _ALL_SUBAPPS is defined if one of the subcommand modules does not comply to the protocol.

Contents of subcommand modules look like this:

import typer


__app_name__: str = "subcommand1"


def _main() -> int:
    ...

def __create__() -> typer.Typer:
    app = typer.Typer()
    app.command(
        name=__app_name__,
        help="Subcommand1 is great.",
    )(_main)
    return app

Let me know what you think! If you find this useful and worthy of mentioning in the documentation, I'd be happy to make a PR for the docs at some point.

Cheers

Bonus: Testing mytool subcommand --help works for all subcommands

I added a convenience function to the __init__:

def list_command_tuples() -> list[tuple[str, ...]]:
    """Return commands as tuples, e.g. [("mytool",), ("mytool", "subcommand1"), (...)]"""
    return [
        (__app_name__,),
        *((__app_name__, subapp.__app_name__) for subapp in _ALL_SUBAPPS),
    ]

This helped me write a simple integration test checking that at least "mytool subcommand{1,2} --help" works.

import subprocess

import pytest

from mytool._cli.mytool import list_command_tuples


@pytest.mark.parametrize(
    "cmd_tpl", list_command_tuples(), ids=lambda tpl: "_".join(tpl)
)
def test_cli_help_exits_successfully(cmd_tpl: tuple[str, ...]):
    """Running command with --help option returns 0."""
    result = subprocess.run([*cmd_tpl, "--help"], capture_output=True)
    assert result.returncode == 0