Cappa: Declarative CLI Argument Parser

Cappa is a declarative command line parsing library that uses runtime type inspection to infer CLI argument behavior, generate help text, and provide dynamic completion. It offers four primary styles of CLI declaration:

1. Classes: Fields in a class correspond to CLI arguments or subcommands.
2. Functions: Arguments in a function correspond to CLI arguments.
3. Methods: Class fields correspond to parent arguments, while methods act as subcommands.
4. Imperative Construction: Manually building the CLI structure using cappa.Command instead of relying on inference.

Cappa supports two execution modes:

• parse: Returns an instance of the input structure (similar to argparse).
• invoke: Calls a function based on the selected subcommand (similar to click or typer).

The backend argument in cappa.invoke and cappa.parse can technically be used to provide a custom backend implementation (e.g., for click). This allows you to retain Cappa's pre-parsing, inference, and dependency injection infrastructure while using a different underlying parser.

Warning: The backend interface is not yet stabilized. The input/output shapes of a backend may change in future versions. It is recommended to discuss custom backend requirements with the maintainers before relying on specific implementation details.

Cappa separates its architecture into two distinct parts:

1. Frontend: The primary public API, including annotation inference, the invoke/dependency system, and object/function definitions.
2. Backend: The component responsible for taking the object graph produced by your CLI definition and parsing the raw CLI input into a format the frontend understands. The backend also controls the help-text formatter.

While the frontend handles the logic and dependency injection, the backend handles the actual mechanics of argument parsing and help generation.

Cappa uses Python type annotations to perform two primary functions:

1. Arg-level inference: Automatically determining parsing behavior (like whether an argument is a flag, a positional argument, or an option) based on the type.
2. Mapping inference: Automatically converting raw string inputs from the CLI into the specified Python types (e.g., converting a string to an int, datetime, or pathlib.Path).

If the automatic inference does not meet your needs, you can override it by providing a custom parse function within an Arg() annotation.

While libraries like Pydantic-CLI or Pydantic-Settings focus on translating CLI arguments into a Pydantic model instance, Cappa is designed to describe an arbitrary CLI shape using types and models.

Key differences include:

• Shape Control: Cappa can describe complex, nested CLI structures (subcommands, specific argument groupings) that Pydantic-based tools often flatten or limit to single-level commands.
• Type Inference: Cappa provides comprehensive type inference for complex types (e.g., foo: tuple[int, str] | None) to translate them into logical CLI argument shapes, whereas Pydantic-based tools may rely on JSON-style input parsing for complex types.

Any supported dataclass-like class used as a top-level command can also function as a subcommand. Subcommands are organized into a tree by having a parent command define which subcommands are available using the Subcommands type hint.

To implement subcommands, define a field in your parent command with the type Subcommands[UnionOfSubcommands].

from cappa import Subcommands
from dataclasses import dataclass
from typing import Union

@dataclass
class SubcmdOne:
    name: str

@dataclass
class SubcmdTwo:
    name: str

@dataclass
class Command:
    subcommand: Subcommands[Union[SubcmdOne, SubcmdTwo]]

The cappa.Default construct allows you to specify an ordered chain of fallback options. You can chain these using the | operator. If a handler returns cappa.Empty, cappa moves to the next item in the chain.

Common Fallback Patterns:

• Static Fallback: Arg(default=Default(Env("FOO"), default=4)) (Try env var FOO, then fallback to 4).
• Interactive Fallback: Arg(default=Env("FOO") | Prompt("Enter value")) (Try env var FOO, then prompt the user).

Note: Default.default (the static fallback) does not invoke the Arg.parse parser.

# Chain: Env Var -> User Prompt -> Static Value
foo: Annotated[int, Arg(default=Env("FOO") | Prompt("Gimme") | 4)]

To create a CLI with subcommands, define a field in your main dataclass using cappa.Subcommands[T], where T is a Union of the command dataclasses.

Use the @cappa.command(name="...") decorator on your command dataclasses to specify the literal string used in the CLI (e.g., todo add instead of the class name AddCommand).

from __future__ import annotations
from dataclasses import dataclass
import cappa

@dataclass
class Todo:
    command: cappa.Subcommands[AddCommand | ListCommand]

@cappa.command(name="add")
@dataclass
class AddCommand:
    todo: str

@cappa.command(name="list")
@dataclass
class ListCommand:
    ...

cappa.invoke(Todo)

Cappa provides two primary ways to interface with your CLI definitions, depending on whether you want an argparse-style or a click-style workflow:

1. cappa.parse (argparse-style): Use this if you want the library to simply parse command-line arguments and return a populated instance of your dataclass. You are responsible for calling your logic manually using the returned object.
2. cappa.invoke (click-style): Use this if you want the library to handle the execution flow. By using the @cappa.command(invoke=...) decorator on your class, cappa.invoke will automatically dispatch the parsed arguments to your target function.