tmt.cli package

Submodules

tmt.cli.status module

tmt status implementation

Module contents

Basic classes and code for tmt command line interface

class tmt.cli.CliInvocation(context: Context | None, options: dict[str, Any])

Bases: object

A single CLI invocation of a tmt subcommand.

Bundles together the Click context and options derived from it. A context alone might be good enough, but sometimes tmt needs to modify saved options. For custom command line options injected manually ‘sources’ is used to keep the parameter source.

Serves as a clear boundary between invocations of classes representing various tmt subcommands and groups.

context: Context | None
classmethod from_context(context: Context) → CliInvocation
classmethod from_options(options: dict[str, Any]) → CliInvocation

Inject custom options coming from the command line

property option_sources: dict[str, ParameterSource]
options: dict[str, Any]
class tmt.cli.Context(command: Command, parent: Context | None = None, info_name: str | None = None, obj: Any | None = None, auto_envvar_prefix: str | None = None, default_map: MutableMapping[str, Any] | None = None, terminal_width: int | None = None, max_content_width: int | None = None, resilient_parsing: bool = False, allow_extra_args: bool | None = None, allow_interspersed_args: bool | None = None, ignore_unknown_options: bool | None = None, help_option_names: List[str] | None = None, token_normalize_func: Callable[[str], str] | None = None, color: bool | None = None, show_default: bool | None = None)

Bases: Context

Custom click.Context-like class for typing purposes.

Objects of this class are never instantiated, it serves only as a type stub in commands below, to simplify handling and static analysis of context.obj. There is no added functionality, the only change is a much narrower type of obj attribute.

This class shall be used instead of the original click.Context. Click is obviously not aware of our type annotations, and context objects managed by Click would always be of type click.Context, we would just convince mypy their obj attribute is no longer Any.

max_content_width: int | None

The maximum width of formatted content (None implies a sensible default which is 80 for most things).

obj: ContextObject

the user object stored.

class tmt.cli.ContextObject(cli_context: ~tmt.cli.Context, logger: ~tmt.log.Logger, common: ~tmt.utils.Common, fmf_context: ~tmt.utils.FmfContext, tree: ~tmt.base.Tree, steps: set[str] = <factory>, clean: ~tmt.base.Clean | None = None, clean_logger: ~tmt.log.Logger | None = None, clean_partials: ~collections.defaultdict[str, list[~typing.Callable[[], bool]]] = <factory>, run: ~tmt.base.Run | None = None)

Bases: object

Click Context Object container.

In Click terms, this is “an arbitrary object of user data.” In this container, tmt CLI code stores all structures relevant for the command execution. The container itself is then attached to click.Context object Click manages across commands.

clean: Clean | None = None
clean_logger: Logger | None = None
clean_partials: defaultdict[str, list[Callable[[], bool]]]
cli_context: Context
common: Common
fmf_context: FmfContext
logger: Logger
run: Run | None = None
steps: set[str]
tree: Tree
class tmt.cli.CustomGroup(name: str | None = None, commands: MutableMapping[str, Command] | Sequence[Command] | None = None, **attrs: Any)

Bases: Group

Custom Click Group

get_command(context: Context, cmd_name: str) → Command | None

Allow command shortening

list_commands(context: Context) → list[str]

Prevent alphabetical sorting

tmt.cli.EXCEPTION_LOGGER: Logger = <Logger: name=_tmt_bootstrap verbosity=0 debug=0 quiet=False topics=set() apply_colors_output=True apply_colors_logging=True>

A logger to use for exception logging.

Warning

This logger should be used with utmost care for logging exceptions only, no other traffic should be allowed. On top of that, the exception logging is handled by a dedicated function, tmt.utils.show_exception() - if you find yourself in need of logging an exception somewhere in the code, and you think about using this logger or calling show_exception() explicitly, it is highly likely you are not on the right track.

class tmt.cli.HelpFormatter(indent_increment: int = 2, width: int | None = None, max_width: int | None = None)

Bases: HelpFormatter

Custom help formatter capable of rendering ReST syntax

write_dl(rows: Sequence[tuple[str, str]], col_max: int = 30, col_spacing: int = 2) → None

Writes a definition list into the buffer. This is how options and commands are usually formatted.

Parameters:

  • rows – a list of two item tuples for the terms and values.

  • col_max – the maximum width of the first column.

  • col_spacing – the number of spaces between the first and second column.

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

Bases: IntEnum

ALL_TESTS_SKIPPED = 4

Tests were executed, and all reported the skip result.

ERROR = 2

Errors occurred during test execution.

FAIL = 1

There was a fail or warn identified, but no error.

NO_RESULTS_FOUND = 3

No test results found.

SUCCESS = 0

At least one test passed, there was no fail, warn or error.

tmt.cli.pass_context(fn: Callable[Concatenate[Context, P], R]) → Callable[P, R]

Custom click.pass_context()-like decorator.

Complementing the Context, the goal of this decorator to announce the correct type of the context parameter. The original decorator annotates the parameter as click.Context, but that is not what our command callables accept. So, on this boundary between tmt code and click API, we trick type checkers by isolating the necessary type: ignore[arg-type].