From 3e1bbc3372412a051d6ed4601e6b3f2d4a650adc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Milo=C5=A1=20Prchl=C3=ADk?= Date: Sun, 22 Dec 2024 09:24:55 +0100 Subject: [PATCH] Document predefined order values of special phases I threw in a bit of renaming, because some constants were not about plugins only, some were not defaults, i.e. it was not possible to change them, and so on. --- spec/core/order.fmf | 26 ++++++++++++++++++++++++++ tmt/base.py | 1 + tmt/steps/__init__.py | 31 ++++++++++++++++++++++++------- tmt/steps/discover/shell.py | 2 +- tmt/steps/prepare/__init__.py | 6 +++--- tmt/steps/prepare/distgit.py | 11 ++++++++--- tmt/utils/__init__.py | 7 +------ 7 files changed, 64 insertions(+), 20 deletions(-) diff --git a/spec/core/order.fmf b/spec/core/order.fmf index f73658f57e..7b6ae42d9b 100644 --- a/spec/core/order.fmf +++ b/spec/core/order.fmf @@ -1,3 +1,6 @@ +/: + select: true + summary: Order in which the object should be handled description: @@ -14,3 +17,26 @@ example: | link: - implemented-by: /tmt/base.py - verified-by: /tests/core/order + +/predefined-order: + title: Predefined order values + + summary: Predefined order values - summary + + description: | + 30 + Installation of essential plugin and check requirements. + + 50 + The default order of any object. + + 60 + Application of patches by ``rpm-build`` command invoked by + :ref:`discover/fmf` plugin when + ``dist-git-source`` key is used. + + 70 + Installation of packages :ref:`required` by tests. + + 75 + Installation of packages :ref:`recommended` by tests. diff --git a/tmt/base.py b/tmt/base.py index 60c0297b07..092f82563c 100644 --- a/tmt/base.py +++ b/tmt/base.py @@ -88,6 +88,7 @@ # metadata and 1h for scripts defined directly in plans (L2 metadata). DEFAULT_TEST_DURATION_L1 = '5m' DEFAULT_TEST_DURATION_L2 = '1h' +#: The default order of any object. DEFAULT_ORDER = 50 DEFAULT_TEST_RESTART_LIMIT = 1 diff --git a/tmt/steps/__init__.py b/tmt/steps/__init__.py index 28b541dbe9..f52c248796 100644 --- a/tmt/steps/__init__.py +++ b/tmt/steps/__init__.py @@ -68,8 +68,25 @@ DEFAULT_ALLOWED_HOW_PATTERN: Pattern[str] = re.compile(r'.*') -DEFAULT_PLUGIN_METHOD_ORDER: int = 50 +# +# Following are default and predefined order values for various special phases +# recognized by tmt. When adding new special phase, add its order below, and +# do not forget to update the list in /spec/core/order. Please, keep the name +# prefix, so it's easy to find all `PHASE_ORDER_*` constants for documentation. +# + +#: The default order of any object. +# TODO: this is a duplication of tmt.base.DEFAULT_ORDER. Unfortunately, tmt.base +# imports tmt.steps, not the other way around. +# `PHASE_ORDER_DEFAULT = tmt.base.DEFAULT_ORDER` would be way better. +PHASE_ORDER_DEFAULT = 50 +#: Installation of essential plugin and check requirements. +PHASE_ORDER_INSTALL_ESSENTIAL_REQUIRES = 30 +#: Installation of packages :ref:`required` by tests. +PHASE_ORDER_INSTALL_REQUIRES = 70 +#: Installation of packages :ref:`recommended` by tests. +PHASE_ORDER_INSTALL_RECOMMENDS = 75 # Supported steps and actions STEPS: list[str] = ['discover', 'provision', 'prepare', 'execute', 'report', 'finish'] @@ -122,7 +139,7 @@ option( '--order', type=int, - default=DEFAULT_PLUGIN_METHOD_ORDER, + default=PHASE_ORDER_DEFAULT, help='Order in which the phase should be handled.') ]) @@ -189,7 +206,7 @@ class Phase(tmt.utils.Common): def __init__( self, *, - order: int = tmt.utils.DEFAULT_PLUGIN_ORDER, + order: int = PHASE_ORDER_DEFAULT, **kwargs: Any): super().__init__(**kwargs) self.order: int = order @@ -291,7 +308,7 @@ class StepData( name: str = field(help='The name of the step phase.') how: str = field() order: int = field( - default=tmt.utils.DEFAULT_PLUGIN_ORDER, + default=PHASE_ORDER_DEFAULT, help='Order in which the phase should be handled.') when: list[str] = field( default_factory=list, @@ -1170,7 +1187,7 @@ def __init__( name: str, class_: Optional[PluginClass] = None, doc: Optional[str] = None, - order: int = DEFAULT_PLUGIN_METHOD_ORDER + order: int = PHASE_ORDER_DEFAULT ) -> None: """ Store method data """ @@ -1213,7 +1230,7 @@ def usage(self) -> str: def provides_method( name: str, doc: Optional[str] = None, - order: int = DEFAULT_PLUGIN_METHOD_ORDER) -> Callable[[PluginClass], PluginClass]: + order: int = PHASE_ORDER_DEFAULT) -> Callable[[PluginClass], PluginClass]: """ A plugin class decorator to register plugin's method with tmt steps. @@ -1579,7 +1596,7 @@ def _emit_key(key: str) -> None: value = self.get(key) # No need to show the default order - if key == 'order' and value == tmt.base.DEFAULT_ORDER: + if key == 'order' and value == PHASE_ORDER_DEFAULT: return if value is None: diff --git a/tmt/steps/discover/shell.py b/tmt/steps/discover/shell.py index 8fd41dd996..43f868ca67 100644 --- a/tmt/steps/discover/shell.py +++ b/tmt/steps/discover/shell.py @@ -60,7 +60,7 @@ class TestDescription( description: Optional[str] = None enabled: bool = True order: int = field( - # TODO: ugly circular dependency (see tmt.base.DEFAULT_ORDER) + # TODO: ugly circular dependency (see tmt.steps.PHASE_ORDER_DEFAULT) default=50, normalize=lambda key_address, raw_value, logger: 50 if raw_value is None else int(raw_value) diff --git a/tmt/steps/prepare/__init__.py b/tmt/steps/prepare/__init__.py index b0504f31bf..84e5136378 100644 --- a/tmt/steps/prepare/__init__.py +++ b/tmt/steps/prepare/__init__.py @@ -343,19 +343,19 @@ def _emit_phase( pruned_essential_requires, 'essential-requires', 'Install essential required packages', - tmt.utils.DEFAULT_PLUGIN_ORDER_ESSENTIAL_REQUIRES) + tmt.steps.PHASE_ORDER_INSTALL_ESSENTIAL_REQUIRES) _emit_phase( pruned_requires, 'requires', 'Install required packages', - tmt.utils.DEFAULT_PLUGIN_ORDER_REQUIRES) + tmt.steps.PHASE_ORDER_INSTALL_REQUIRES) _emit_phase( pruned_recommends, 'recommends', 'Install recommended packages', - tmt.utils.DEFAULT_PLUGIN_ORDER_RECOMMENDS, + tmt.steps.PHASE_ORDER_INSTALL_RECOMMENDS, missing='skip') # Prepare guests (including workdir sync) diff --git a/tmt/steps/prepare/distgit.py b/tmt/steps/prepare/distgit.py index a4a5e76f24..f66f6ea095 100644 --- a/tmt/steps/prepare/distgit.py +++ b/tmt/steps/prepare/distgit.py @@ -19,6 +19,11 @@ import tmt.steps.discover import tmt.steps.prepare.install +#: Application of patches by ``rpm-build`` command invoked by +#: :ref:`discover/fmf` plugin when +#: ``dist-git-source`` key is used. +PHASE_ORDER_RPMBUILD_BP = 30 + PREPARE_WRAPPER_FILENAME = 'tmt-prepare-wrapper.sh' FEDORA_BUILD_REQUIRES = [Package('@buildsys-build')] @@ -59,7 +64,7 @@ def insert_to_prepare_step( how='install', name='requires (dist-git)', summary='Install required packages of tests detected by dist-git', - order=tmt.utils.DEFAULT_PLUGIN_ORDER_REQUIRES, + order=tmt.steps.PHASE_ORDER_INSTALL_REQUIRES, where=where, package=[]) future_requires: PreparePlugin[Any] = cast( @@ -72,7 +77,7 @@ def insert_to_prepare_step( how='install', name='recommends (dist-git)', summary='Install recommended packages of tests detected by dist-git', - order=tmt.utils.DEFAULT_PLUGIN_ORDER_RECOMMENDS, + order=tmt.steps.PHASE_ORDER_INSTALL_RECOMMENDS, where=where, package=[], missing='skip') @@ -116,7 +121,7 @@ class DistGitData(tmt.steps.prepare.PrepareStepData): option='--phase-name', help="Name of the discover step phase to inject tests to.", internal=True) - order: int = 60 + order: int = PHASE_ORDER_RPMBUILD_BP install_builddeps: bool = field( default=False, option="--install-builddeps", diff --git a/tmt/utils/__init__.py b/tmt/utils/__init__.py index 7b3e7e1b2d..cee6e861f4 100644 --- a/tmt/utils/__init__.py +++ b/tmt/utils/__init__.py @@ -141,13 +141,8 @@ def configure_constant(default: int, envvar: str) -> int: # Hierarchy indent INDENT = 4 -# Default name and order for step plugins +# Default name for step plugins DEFAULT_NAME = 'default' -DEFAULT_PLUGIN_ORDER = 50 -DEFAULT_PLUGIN_ORDER_MULTIHOST = 10 -DEFAULT_PLUGIN_ORDER_ESSENTIAL_REQUIRES = 30 -DEFAULT_PLUGIN_ORDER_REQUIRES = 70 -DEFAULT_PLUGIN_ORDER_RECOMMENDS = 75 # Special process return codes