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 follwing 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 does not come with a native prompt/confirm option. However it does ship with built-in integration with rich.prompt.Prompt.

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 hazzard for testing. cappa.rich.TestPrompt can be used in any CLI-level testing, which relocates rich’s default and stream arguments off the .ask function.

You can create a TestPrompt("message", input='text input', default='some default') to simulate a user inputting values to stdin inside tests.

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(...)