craft_cli package

Submodules

• craft_cli.dispatcher module
• craft_cli.errors module
• craft_cli.helptexts module
• craft_cli.messages module
• craft_cli.pytest_plugin module

Module contents

Interact with Canonical services such as Charmhub and the Snap Store.

exception craft_cli.ArgumentParsingError

Bases: Exception

Exception used when an argument parsing error is found.

class craft_cli.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.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

exception craft_cli.CraftError(message, *, details=None, resolution=None, docs_url=None, logpath_report=True, reportable=True, retcode=1)

Bases: Exception

Signal a program error with a lot of information to report.

Variables

• message – the main message to the user, to be shown as first line (and probably only that, according to the different modes); note that in some cases the log location will be attached to this message.

• details – the full error details received from a third party which originated the error situation

• resolution – an extra line indicating to the user how the error may be fixed or avoided (to be shown together with ‘message’)

• docs_url – an URL to point the user to documentation (to be shown together with ‘message’)

• logpath_report – if the location of the log filepath should be presented in the screen as the final message

• reportable – if an error report should be sent to some error-handling backend (like Sentry)

• retcode – the code to return when the application finishes

Parameters

• message (str) –

• details (Optional[str]) –

• resolution (Optional[str]) –

• docs_url (Optional[str]) –

• logpath_report (bool) –

• reportable (bool) –

• retcode (int) –

class craft_cli.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.EmitterMode(value)

Bases: enum.Enum

An enumeration.

BRIEF = 2

DEBUG = 4

QUIET = 1

TRACE = 5

VERBOSE = 3

class craft_cli.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

exception craft_cli.ProvideHelpException

Bases: Exception

Exception used to provide help to the user.