craft_cli.dispatcher module

Argument processing and command dispatching functionality.

namedtuple craft_cli.dispatcher.CommandGroup(name: str, commands: Sequence[type[BaseCommand]], ordered: bool = False)

Bases: NamedTuple

Definition of a command group.

A list of these is what is passed to the Dispatcher to run commands as part of the application.

Fields:

0.  name (str) – The identifier of the command group (to be used in help texts).

1.  commands (Sequence[type[BaseCommand]]) – A list of the commands belonging in this group.

2.  ordered (bool) – Whether the commands in this group are already in the correct order (defaults to False).

namedtuple craft_cli.dispatcher.GlobalArgument(name: str, type: Literal['flag', 'option'], short_option: str | None, long_option: str, help_message: str)

Bases: NamedTuple

Definition of a global argument to be handled by the Dispatcher.

Fields:

0.  name (str) – Identifier of the argument (the reference in the dictionary returned) by the Dispatcher.pre_parse_args() method)

1.  type (Literal['flag', 'option']) – The argument type: flag for arguments that are set to True if specified (False by default), or option if a value is needed after it.

2.  short_option (Optional[str]) – The short form of the argument (a dash with a letter, e.g. -s); it can be None if the option does not have a short form.

3.  long_option (str) – The long form of the argument (two dashes and a name, e.g. --secure).

4.  help_message (str) – the one-line text that describes the argument, for building the help texts.

class craft_cli.dispatcher.BaseCommand(config: dict[str, Any] | None)

Bases: object

Base class to build application commands.

Subclass this to create a new command; the subclass must define the name, help_msg, and overview attributes. Additionally, it may override the common and hidden attributes to change from their default values.

The subclass may also override some methods for the proper command behaviour (see each method’s docstring).

Finally, the subclass must be declared in the corresponding section of command groups indicated to the Dispatcher.

name: str

The identifier in the command line, like “build” or “pack”.

help_msg: str

A one-line help message for user documentation.

overview: str

Longer, multi-line text with the whole command description.

common: bool = False

Whether this is a common/starter command, which are prioritized in the help (defaults to False).

hidden: bool = False

Do not show in help texts, useful for aliases or deprecated commands (defaults to False).

fill_parser(parser: _CustomArgumentParser) → None

Specify command’s specific parameters.

Each command parameters are independent of other commands, but note there are some global ones (see main.Dispatcher._build_argument_parser).

If this method is not overridden, the command will not have any parameters.

Parameters:

parser – The object to fill with this command’s parameters.

run(parsed_args: Namespace) → int | None

Execute command’s actual functionality.

It must be overridden by the command implementation.

Parameters:

parsed_args – The parsed arguments that were defined in fill_parser().

Returns:

This method should return None or the desired process’ return code.

class craft_cli.dispatcher.Dispatcher(appname: str, commands_groups: list[CommandGroup], *, summary: str = '', extra_global_args: list[GlobalArgument] | None = None, default_command: type[BaseCommand] | None = None, docs_base_url: str | None = None)

Bases: object

Set up infrastructure and let the needed command run.

♪♫”Leeeeeet, the command ruuun”♪♫ https://www.youtube.com/watch?v=cv-0mmVnxPA

Parameters:

• appname – the name of the application

• commands_groups – a list of command groups available to the user

• summary – the summary of the application (for help texts)

• extra_global_args – other automatic global arguments than the ones provided automatically

• default_command – the command to run if none was specified in the command line

• docs_base_url – The base address of the documentation, for help messages.

load_command(app_config: Any) → BaseCommand

Load a command.

parsed_args() → Namespace

Get the parsed command-line arguments.

pre_parse_args(sysargs: list[str], app_config: Any = None) → dict[str, Any]

Pre-parse sys args.

Several steps:

• extract the global options and detects the possible command and its args

• validate global options and apply them

• validate that command is correct (NOT loading and parsing its arguments)

If provided, app_config is passed to the command to be validated.

run() → int | None

Really run the command.