craft_cli.dispatcher module

Argument processing and command dispatching functionality.

class craft_cli.dispatcher.BaseCommand(config)

Bases: object

Base class to build application commands.

Subclass this to create a new command; the subclass must define the following attributes:

• name: the identifier in the command line

• help_msg: a one line help for user documentation

• overview: a longer multi-line text with the whole command description

Also it may override the following one to change its default:

• common: if it’s a common/starter command, which are prioritized in the help (default to False)

• hidden: do not show in help texts, useful for aliases or deprecated commands (default to False)

It also must/can override some methods for the proper command behaviour (see each method’s docstring).

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

Parameters

config (Optional[Dict[str, Any]]) –

common = False

fill_parser(parser)

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 (_CustomArgumentParser) –

Return type

None

help_msg: Optional[str] = None

hidden = False

name: Optional[str] = None

overview: Optional[str] = None

run(parsed_args)

Execute command’s actual functionality.

It must be overridden by the command implementation.

This will receive parsed arguments that were defined in :meth:.fill_parser.

It should return None or the desired process’ return code.

Parameters

parsed_args (Namespace) –

Return type

Optional[int]

class craft_cli.dispatcher.CommandGroup(name, commands)

Bases: tuple

Definition of a command group.

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

Parameters

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

• commands – a list of the commands in this group.

commands

name

class craft_cli.dispatcher.Dispatcher(appname, commands_groups, *, summary='', extra_global_args=None, default_command=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 (str) – the name of the application

• commands_groups (List[CommandGroup]) – a list of command groups available to the user

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

• extra_global_args (Optional[List[GlobalArgument]]) – other automatic global arguments than the ones provided automatically

• default_command (Optional[Type[BaseCommand]]) – the command to run if none was specified in the command line

load_command(app_config)

Load a command.

Parameters

app_config (Any) –

Return type

BaseCommand

pre_parse_args(sysargs)

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)

Parameters

sysargs (List[str]) –

run()

Really run the command.

Return type

Optional[int]

class craft_cli.dispatcher.GlobalArgument(name, type, short_option, long_option, help_message)

Bases: tuple

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

Parameters

• name – identifier of the argument (the reference in the dictionary returned by Dispatcher.pre_parse_args method)

• type – 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.

• short_option – 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.

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

• help_message – the one-line text that describes the argument, for building the help texts.

help_message

long_option

name

short_option

type