Commands¶

A command can be as simple as a dataclass-like object, with no additional annotations. Supported object-types include:

dataclasses
pydantic models
pydantic dataclasses
attrs classes

from dataclasses import dataclass

@dataclass
class Dataclass:
    name: str

# or
from pydantic import BaseModel

class PydanticModel(BaseModel):
    name: str

# or

from pydantic.dataclasses import dataclass as pydantic_dataclass

@pydantic_dataclass
class PydanticDataclass:
    name: str

# or
from attr import define

@define
class AttrsClass:
    name: str


from cappa import parse

p1 = parse(Dataclass)
assert isinstance(p1, Dataclass)

p2 = parse(PydanticModel)
assert isinstance(p2, PydanticModel)

p3 = parse(PydanticDataclass)
assert isinstance(p3, PydanticDataclass)

p4 = parse(AttrsClass)
assert isinstance(p4, PAttrsClass)

However, you can additionally wrap the class in the cappa.command decorator to gain access to (described below) more customizability (such as customizing the command’s name) and behavior (such as invoke).

Note

The wrapped class is directly returned from the decorator. So unlike click, the resultant object can be directly used in the same way that you’d have been able to do sans decorator.

class cappa.Command

Parameters:

cmd_cls – The class representing the command/subcommand
name – The name of the command. If omitted, the name of the command will be the name of the cls, converted to dash-case.
help – Optional help text. If omitted, the cls docstring will be parsed, and the headline section will be used to document the command itself, and the arguments section will become the default help text for any params/options.
description – Optional extended help text. If omitted, the cls docstring will be parsed, and the extended long description section will be used.
invoke – Optional command to be called in the event parsing is successful. In the case of subcommands, it will only call the parsed/selected function to invoke. The value can either be a callable object or a string. When the value is a string it will be interpreted as module.submodule.function; the module will be dynamically imported, and the referenced function invoked.
hidden – If True, the command will not be included in the help output. This option is only relevant to subcommands.
default_short – If True, all arguments will be treated as though annotated with Annotated[T, Arg(short=True)], unless otherwise annotated.
default_true – If True, all arguments will be treated as though annotated with Annotated[T, Arg(long=True)], unless otherwise annotated.
deprecated – If supplied, the argument will be marked as deprecated. If given True, a default message will be generated, otherwise a supplied string will be used as the deprecation message.

add_meta_actions(help=None, version=None, completion=None)

Parameters:

help (cappa.arg.Arg | None)
version (cappa.arg.Arg | None)
completion (cappa.arg.Arg | None)

arguments

cmd_cls

classmethod collect(command)

Parameters:: command (Command[T])
Return type:: Command[T]

default_long = False

default_short = False

deprecated = False

description

classmethod get(obj)

Parameters:: obj (type[T] | Command[T])
Return type:: Command[T]

help

hidden = False

invoke

map_result(command, prog, parsed_args)

Parameters:

command (Command[T])
prog (str)

Return type:

name

classmethod parse_command(command, *, output, backend, argv=None)

Parameters:

command (Command[T])
output (cappa.output.Output)
backend (Callable)
argv (list[str] | None)

Return type:

tuple[Command, Command[T], T]

real_name()

Return type:: str

value_arguments()

Command/Subcommand Name¶

By default, the name of the command is inferred from the name of the containing class, and converted to dash-case. For example Example would become example, and SomeLongName would become some-long-name.

The name field can be used to override this behavior.

Help/Description Text¶

See Help Text Inference for details.

Command also accepts a “description”, which constitutes the extended text section below.

class Example:
    """Example CLI.

    With some long description.

    Arguments:
        foo: The number of foos
    """
    foo: int

would produce something like the following help text:

Usage: example.py [-h]

Example CLI. With some long description.

Positional Arguments:
  foo                  The number of foos

Invoke¶

See Invoke documentation for more details. Essentially this invokes a function upon a command/subcommand being selected during parsing, when using cappa.invoke instead of cappa.parse.