💡 write type-safe and elegant CLIs with a clear separation of concerns.

Features

• Argument parsing based on type annotation (including runtime validation).
• Support for many common types.
• Clear separation of concern between argument parsing and business logic.
• Support for super-low-latency shell auto-completions.
• Great for writing sub-command CLIs.
• Very lightweight.
• No dependencies.
• Fully typed itself, no extra type stubs required.
• Offers both a high-level and a low-level API. The high-level API generally requires less code to write, is fully based on type annotations, and is the preferred way for writing new CLIs. The low-level API is mainly a low-effort migration path for incorporating type-safety into existing CLIs based on argparse.

Install

$ pip install typed-argparse

The only requirement is a modern Python (3.10+).

Basic Usage

import typed_argparse as tap


# 1. Argument definition
class Args(tap.TypedArgs):
    my_arg: str = tap.arg(help="some help")
    number_a: int = tap.arg(default=42, help="some help")
    number_b: Optional[int] = tap.arg(help="some help")
    verbose: bool = tap.arg(help="some help")
    names: List[str] = tap.arg(help="some help")


# 2. Business logic
def runner(args: Args):
    print(f"Running my app with args:\n{args}")


# 3. Bind argument definition + business logic & run
def main() -> None:
    tap.Parser(Args).bind(runner).run()

Documentation

See full documentation.

Changes

See change log.

License

This project is licensed under the terms of the MIT license.

Develop

Project uses uv for dependency management, to install development environment simply run uv sync. uv run $SCRIPT will also automatically sync dependencies based on current pyproject.toml/uv.lock.