tmt.plugins package

Subpackages

Module contents

Handle Plugins

class tmt.plugins.ModuleImporter(module: str, exc_class: type[Exception], hint_id: str)

Bases: Generic[ModuleT]

Import and return a module when called.

A helper class for importing modules that cannot be imported in boot time. Constructs a callable that, when called, would import and return a given module. The module may be already imported, then it’s taken from sys.modules.

class tmt.plugins.PluginRegistry(name: str)

Bases: Generic[RegisterableT]

A container for plugins of shared purpose.

A fancy wrapper for a dictionary at its core, but allows for nicer annotations and more visible semantics when working with plugins.

For the basic use cases, the following should provide overview of the usage:

# Create a new registry called `my plugins`, collecting plugins
# of `MyPlugin` class:
my_registry: PluginRegistry[type[MyPlugin]] = PluginRegistry('my plugins')

# Create a decorator to mark classes as plugins belonging to the
# new registry:
my_plugin = my_registry.create_decorator()

# Register a couple of plugins:
@my_plugin('foo')
class Foo(MyPlugin):
    ...

@my_plugin('bar')
class Bar(MyPlugin):
    ...

# Work with plugins:
my_registry.get_plugin('foo')  # Foo
my_registry.get_plugin('baz')  # None

my_registry.iter_plugin_ids()  # 'foo', 'bar', ...
my_registry.iter_plugins()     # Foo, Bar, ...
my_registry.items()            # ('foo', Foo), ('bar', Bar), ...
create_decorator(on_register: Callable[[Concatenate[str, RegisterableT, P]], None] | None = None) → Callable[[Concatenate[str, P]], Callable[[RegisterableT], RegisterableT]]

Create a decorator that, applied to classes, registers them as plugins.

Parameters:

on_register – if specified, it is called for every plugin being registered. It must accept plugin ID and plugin class, any additional positional and keyword arguments are made part of the decorator signature.

Returns:

a decorator registering the decorated class with the registry. The decorator must accept a single argument, the plugin ID, plus any additional positional and keyword arguments accepted by the on_register callback.

get_plugin(plugin_id: str) → RegisterableT | None

Find a plugin by its id.

Returns:

plugin or None if no such id has been registered.

items() → Iterator[tuple[str, RegisterableT]]
iter_plugin_ids() → Iterator[str]
iter_plugins() → Iterator[RegisterableT]
register_plugin(*, plugin_id: str, plugin: RegisterableT, raise_on_conflict: bool = True, logger: Logger) → None

Register a plugin with this registry.

Parameters:

  • plugin_id – id of the plugin. Works as a label or name, and must may not be used in this registry yet.

  • plugin – a plugin to register.

  • raise_on_conflict –

    if set, an exception would be raised when id was already used.

    Note

    As of now, only a warning is logged, no exception is raised. Plugin discovery often happens in import time, and it is hard to manage it correctly without more changes in code.

  • logger – used for logging.

tmt.plugins.REGISTRIES: list[PluginRegistry[Any]] = [<tmt.plugins.PluginRegistry object>, <tmt.plugins.PluginRegistry object>, <tmt.plugins.PluginRegistry object>, <tmt.plugins.PluginRegistry object>, <tmt.plugins.PluginRegistry object>, <tmt.plugins.PluginRegistry object>, <tmt.plugins.PluginRegistry object>, <tmt.plugins.PluginRegistry object>, <tmt.plugins.PluginRegistry object>, <tmt.plugins.PluginRegistry object>, <tmt.plugins.PluginRegistry object>, <tmt.plugins.PluginRegistry object>, <tmt.plugins.PluginRegistry object>, <tmt.plugins.PluginRegistry object>, <tmt.plugins.PluginRegistry object>, <tmt.plugins.PluginRegistry object>, <tmt.plugins.PluginRegistry object>]

A collection of known registries.

tmt.plugins.discover(path: Path) → Iterator[str]

Discover available plugins for given paths

tmt.plugins.explore(logger: Logger, again: bool = False) → None

Explore all available plugin locations

By default plugins are explored only once to save time. Repeated call does not have any effect. Use again=True to force plugin exploration even if it has been already completed before.

tmt.plugins.import_member(*, module: str, member: str, logger: Logger) → tuple[ModuleT, Any]

Import member from given module, handle errors nicely

tmt.plugins.import_module(*, module: str, path: Path | None = None, logger: Logger) → ModuleT

Import a module.

Parameters:

  • module – name of a module to import. It may represent a submodule as well, using common dot notation (foo.bar.baz).

  • path – if specified, it would be incorporated in exception message.

Returns:

imported module.

Raises:

SystemExit – when import fails.