Rich¶

Color¶

Colored output, including help-text generation, is automatically enabled. invoke or parse both accept a color: bool = True argument which can be used to enable/disable the colored output directly. Alternatively, rich automatically respects the NO_COLOR environment variable for disabling colored output.

You can control individual styling of the help text by including rich directives inside the help text text. For example Arg(help="I need [bold]Help[/bold]!").

Theming¶

You can define your own rich Theme object and supply it into invoke or parse, which will used when rendering help-text output (and error messaging).

Cappa’s theme defines and uses the following style groups, which you would need to also supply:

cappa.prog
cappa.group
cappa.arg
cappa.arg.name
cappa.subcommand
cappa.help

Prompt/Confirm¶

Cappa integrates directly with rich.prompt.Prompt/rich.prompt.Confirm.

You can directly make use of confirm/prompt from within your code anywhere, and it should “just work”

from rich.prompt import Prompt

name = Prompt.ask("Enter your name")

Alternatively, a Prompt object can be used as a default= value for a cappa.Arg instance.

import cappa
from rich.prompt import Prompt

@dataclass
class Test:
    name: Annotated[str, cappa.Arg(default=Prompt("Enter one of these", choices=['one', 'two', 'three']))]

result = parse(Test)

In the event the value for that argument was omitted at the command-line, the prompt will be evaluated.

Note

Input prompts can be a hazard for testing. As such, you can supply input=StringIO(...) to either of parse/invoke as a way to write tests that exercise the prompt code.

Pretty Tracebacks¶

Prettily backending tracebacks can be a UX improvement for your CLI. Cappa does not define any specific integration with rich for tracebacks, given that you simply install rich’s native traceback handler before calling parse/invoke.

import cappa
from rich.traceback import install

def main():
    install(show_locals=True)
    cappa.invoke(...)