terracomp-typer 0.0.2

No project description provided

terracomp-typer

This package allows you to easily build a Typer CLI application from a Python module hierarchy.

Quickstart

$ tree src/mypackage/commands/
src/mypackage/
├── __init__.py
├── __main__.py
└── commands
    ├── __init__.py
    ├── hello.py
    └── bye.py

# src/mypackage/commands/hello.py
def main(name: str) -> None:
    print("Hello,", name)

# src/mypackage/__main__.py
from terracomp_typer import build_app_from_module

if __name__ == "__main__":
    app = build_app_from_module("mypackage.commands")
    app()

Features

• Packages are treated as command groups and may define a def callback(): ... (see Typer.add_callback()).
• Modules are treated as commands and must define a def main(): ... (see Typer.command()).
• Underscores in package or module names are normalized to hyphens (e.g my_command -> my-command).
• Command(-group) help text is extracted from the package or module docstring, or from the main() docstring.
• [WIP] Improved and dynamic dependency injection.
• [Planned] Support for new-style type hints in older Python versions (e.g. str | None).

Dependency Injection

The terracomp_typer.DependencyInjector is essentially a mapping of types to a corresponding implementation. It allows you to bind any function to the given dependencies based on the function signature.

The build_app_from_module() takes a dependencies argument which populates a DependencyInjector. All callback() and main() functions encountered and added to a typer.Typer object are first bound to the dependencies that can be served by the injector.

The types for which injection can take place must be known in advance. If the implementation is not known in advance, a callback() can accept the DependencyInjector as an argument and inform about the dependencies that will be provided by the callback, allowing any of its subcommands to resolve it.

# src/mypackages/commands/__init__.py
"""
This is a cool CLI that uses terracomp-typer.
"""

from mypackage.config import CliConfig
from pathlib import Path
from terracomp_typer import DependencyInjector, DelayedBinding
from typer import Option

def callback(
    config_file: Path = Option(Path("~/.config/mypackage.ini"), help="Path to the configuration file."),
    dependencies: DependencyInjector = DelayedBinding(CliConfig),
) -> None:
    dependencies.register_supplier(CliConfig, lambda: CliConfig.load(config_file))

# src/mypackage/commands/hello.py
from mypackage.config import CliConfig

def main(name: str, config: CliConfig) -> None:
    # ...

In the above example, the config parameter is not passed by Typer, but instead by the DependencyInjector per the implementation in the previous callback() snippet.

Known caveats

• Only concrete types are supported (no Optional[CliConfig] or vice versa).

[Planned] New-style type hint support

Through typeapi, we can convert new-tyle type hints such as str | None or list[int] to their corresponding representation using typing before the function signature is parsed by Typer.