craft_cli package

Submodules

Module contents

A Command Line Client builder.

exception craft_cli.ArgumentParsingError[source]

Bases: Exception

Exception used when an argument parsing error is found.

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

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[source]

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[source]

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.

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

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:

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

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

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

exception craft_cli.CraftCommandError(message: str, *, stderr: str | bytes | None, **kwargs: Any)[source]

Bases: CraftError

A CraftError with precise error output from a command.

This exception class augments CraftError with the addition of a stderr parameter. This parameter is meant to hold the standard error contents of the failed command - as such, it sits between the typically brief “message” and the “details” parameters from the point of view of verbosity.

It’s meant to be used in cases where the executed command’s standard error is helpful enough to the user to be worth the extra text output.

property stderr: str | None
exception craft_cli.CraftError(message: str, *, details: str | None = None, resolution: str | None = None, docs_url: str | None = None, logpath_report: bool = True, reportable: bool = True, retcode: int = 1, doc_slug: str | None = None)[source]

Bases: Exception

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

message: str

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: str | None

The full error details received from a third party which originated the error situation.

resolution: str | None

An extra line indicating to the user how the error may be fixed or avoided (to be shown together with message).

docs_url: str | None

An URL to point the user to documentation (to be shown together with message).

logpath_report: bool

Whether the location of the log filepath should be presented in the screen as the final message.

reportable: bool

If an error report should be sent to some error-handling backend (like Sentry).

retcode: int

The code to return when the application finishes.

doc_slug: str | None

The slug to the user documentation. Needs a base url to form a full address. Note that docs_url has preference if it is set.

class craft_cli.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)[source]

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[source]

Load a command.

parsed_args() → Namespace[source]

Get the parsed command-line arguments.

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

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[source]

Really run the command.

class craft_cli.EmitterMode(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

The different modes the Emitter can be set.

QUIET = 1
BRIEF = 2
VERBOSE = 3
DEBUG = 4
TRACE = 5
namedtuple craft_cli.GlobalArgument(name: str, type: Literal['flag', 'option'], short_option: str | None, long_option: str, help_message: str)[source]

Bases: NamedTuple

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

Fields:

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

  2.  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.

  3.  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.

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

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

exception craft_cli.ProvideHelpException[source]

Bases: Exception

Exception used to provide help to the user.