Console Output

By default, cappa.parse or cappa.invoke will internally construct an Output object which controls the format of all console output, including how Exit and errors are formatted.

Alternatively cappa.parse and cappa.invoke both accept Output instances as an optional input, allowing you to customize the instance or otherwise make use of it before/after the CLI parse time.

Any Output output will automatically make use of rich, and thus has access to its native styling syntax, and the ability to output native rich constructs.

Producing Output

An invoke handler which depends on an argument annotated as Output will be automatically provided with the Output instance.

import cappa
from dataclasses import dataclass

@cappa.command()
def cli(output: Output):
    output("Hi!") # e.g. output.output("Hi!")


cappa.invoke(cli)

# or

@cappa.command(invoke=cli)
@dataclass
class CLI:
    ...

cappa.invoke(cli)

Note

If you’re familiar with click, click.echo is roughly equivalent to Output.output.

You can alternatively call Output.error to make use of error-specific default formatting/coloring

Exiting and Exit Codes

Cappa provides an Exit class to allow someone to gracefully exit the program, without emitting a traceback.

raise cappa.Exit(message="Oh no!", code=1)
# or
raise cappa.Exit("Oh no!", code=1)
# or
raise cappa.Exit(code=1)
# or
raise cappa.Exit("Graceful exit")  # i.e. status code 0!

If Exit is encountered anywhere within cappa’s running context (e.g. an invoke handler, a parser, an action, etc), it will automatically Output the message using the method appropriate to the exit code (code=0 -> Output.output and code>0 -> Output.error), before gracefully exiting.

Customizing default formatting

cappa.parse and cappa.invoke both accept Output instances as an optional input, allowing you to customize default formatting.

  • output_format (default {message}): Exit code == 0

  • error_format (default {short_help}\n\n[red]Error[/red]: {message}): Exit code != 0

If, for example, you did not want to include short_help by default, and wanted “Error” to be orange, you could do as follows:

output = cappa.Output(error_format="[orange]Error[/orange]: {message}")
cappa.parse(Command, output=output)

API