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
, andoverview
attributes. Additionally, it may override thecommon
andhidden
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).
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:
name (
str
) – The identifier of the command group (to be used in help texts).commands (
Sequence
[type
[BaseCommand
]]) – A list of the commands belonging in this group.ordered (
bool
) – Whether the commands in this group are already in the correct order (defaults to False).
- 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)[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.
- 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)[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
- load_command(app_config: Any) BaseCommand [source]¶
Load a command.
- class craft_cli.EmitterMode(value, names=None, *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:
name (
str
) – Identifier of the argument (the reference in the dictionary returned) by theDispatcher.pre_parse_args()
method)type (
Literal
['flag'
,'option'
]) – The argument type:flag
for arguments that are set toTrue
if specified (False
by default), oroption
if a value is needed after it.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.long_option (
str
) – The long form of the argument (two dashes and a name, e.g.--secure
).help_message (
str
) – the one-line text that describes the argument, for building the help texts.