Extend resource_files to general Traversables

.pre-commit-config.yaml

@@ -32,6 +32,8 @@ repos:
  #
  # For now, we simply copy & paste from pyproject.toml :(
  additional_dependencies:
+ - "importlib-metadata>=3.6.0; python_version < '3.10'"
+ - "importlib-resources; python_version < '3.10'"
  - "click>=8.0.3,!=8.1.4" # 8.1.3 / 8.1.6 TODO type annotations tmt.cli.Context -> click.core.Context click/issues/2558
  - "docutils>=0.16" # 0.16 is the current one available for RHEL9
  - "fmf>=1.3.0"
@@ -80,6 +82,8 @@ repos:
  #
  # For now, we simply copy & paste from pyproject.toml :(
  additional_dependencies:
+ - "importlib-metadata>=3.6.0; python_version < '3.10'"
+ - "importlib-resources; python_version < '3.10'"
  - "click>=8.0.3,!=8.1.4" # 8.1.3 / 8.1.6 TODO type annotations tmt.cli.Context -> click.core.Context click/issues/2558
  - "docutils>=0.16" # 0.16 is the current one available for RHEL9
  - "fmf>=1.3.0"

docs/code/plugin-introduction.rst

@@ -16,6 +16,11 @@ provided in the ``TMT_PLUGINS`` environment variable and from
  Consider adding a static type checker (e.g. ``mypy``) in your
  plugin's CI using the ``main`` branch of ``tmt``.
 
+.. versionadded:: 1.38
+ You can use ``tmt.resources`` entry point to inject resource
+ files to be used for tmt, e.g. schemas or templates. See
+ :ref:`additional-resources` for more details.
+
 
 Inheritance
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -62,3 +67,48 @@ features which cannot be covered by generic ssh implementation of
 the ``Guest`` class.
 
 __ https:/teemtee/tmt/tree/main/examples/plugins
+
+.. additional-resources:
+
+Additional resource files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In order to make resource files available to the base ``tmt``
+execution, you need to point a ``tmt.resources`` entry point to the
+root python package where the resource files are located from, e.g.
+with in the ``examples/plugins``:
+
+.. code-block:: toml
+ :caption: pyproject.toml
+ :emphasize-lines: 5,6
+
+ [project.entry-points."tmt.plugin"]
+ ProvisionExample = "example.provision:ProvisionExample"
+ DiscoverExample = "example.discover:DiscoverExample"
+
+ [project.entry-points."tmt.resources"]
+ ResourcesExample = "example"
+
+you can, for example, add a json schema file for the plugins
+implemented above by including the schema files under a ``schemas``
+folder:
+
+.. code-block:: shell
+
+ $ tree ./example
+ ./example
+ ├── __init__.py
+ ├── discover.py
+ ├── provision.py
+ └── schemas
+ ├── discover
+ │ └── example.yaml
+ └── provision
+ └── example.yaml
+
+.. note::
+
+ Both the entry-point entries as well as any resource file
+ under the ``tmt.resources`` path **must** have unique names.
+ Consider namespacing all relevant entries with the name of the
+ project or an unambiguous derivative of it.

docs/releases.rst

@@ -4,6 +4,13 @@
  Releases
 ======================
 
+tmt-1.38.0
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+External plugins can inject additional resources to be used by tmt using
+the ``tmt.resources`` entry-point, e.g. to extend the schema validation
+or tmt templates.
+
 tmt-1.37.0
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

examples/plugins/discover.py → examples/plugins/example/discover.py

@@ -1,11 +1,23 @@
+import dataclasses
+
 import tmt
 import tmt.steps
 import tmt.steps.discover
+import tmt.utils
 
 # See the online documentation for more details about writing plugins
 # https://tmt.readthedocs.io/en/stable/plugins.html
 
 
+@dataclasses.dataclass
+class DiscoverExampleData(tmt.steps.discover.DiscoverStepData):
+ path: str = tmt.utils.field(
+ default=".",
+ option=('-p', '--path'),
+ metavar='ROOT',
+ help='Path to the metadata tree root.')
+
+
 @tmt.steps.provides_method('example')
 class DiscoverExample(tmt.steps.discover.DiscoverPlugin):
  """
@@ -16,6 +28,8 @@ class DiscoverExample(tmt.steps.discover.DiscoverPlugin):
  of configuration examples as well.
  """
 
+ _data_class = DiscoverExampleData
+
  def show(self):
  """ Show plugin details for given or all available keys """
  super().show([])
@@ -48,7 +62,8 @@ def go(self):
  print("Code should prepare environment for tests.")
 
  # Discover available tests
- self._tests = tmt.Tree(logger=self._logger, path=".").tests()
+ self._tests = tmt.Tree(logger=self._logger,
+ path=self.data.path).tests()
 
  def tests(self):
  """

examples/plugins/example/schemas/discover/example.yaml

@@ -0,0 +1,22 @@
+$id: /schemas/discover/example
+$schema: https://json-schema.org/draft-07/schema
+
+type: object
+additionalProperties: false
+
+properties:
+ how:
+ type: string
+ enum:
+ - example
+ path:
+ $ref: "/schemas/common#/definitions/fmf_id/properties/path"
+
+ # Other basic discover properties
+ name:
+ type: string
+ order:
+ $ref: "/schemas/core#/definitions/order"
+
+required:
+ - how

examples/plugins/example/schemas/provision/example.yaml

@@ -0,0 +1,20 @@
+$id: /schemas/provision/example
+$schema: https://json-schema.org/draft-07/schema
+
+type: object
+additionalProperties: false
+
+properties:
+ how:
+ type: string
+ enum:
+ - example
+
+ # Other basic provision properties
+ name:
+ type: string
+ order:
+ $ref: "/schemas/core#/definitions/order"
+
+required:
+ - how

examples/plugins/pyproject.toml

@@ -12,10 +12,12 @@ dependencies = [
 
 [tool.hatch.build.targets.wheel]
 packages = [
- "discover.py",
- "provision.py",
+ "example",
 ]
 
 [project.entry-points."tmt.plugin"]
-ProvisionExample = "provision:ProvisionExample"
-DiscoverExample = "discover:DiscoverExample"
+ProvisionExample = "example.provision:ProvisionExample"
+DiscoverExample = "example.discover:DiscoverExample"
+
+[project.entry-points."tmt.resources"]
+ResourcesExample = "example"

pyproject.toml

@@ -30,6 +30,8 @@ classifiers = [
  "Operating System :: POSIX :: Linux",
  ]
 dependencies = [ # F39 / PyPI
+ "importlib-metadata>=3.6.0; python_version < '3.10'", # Backporting selectable entry_points
+ "importlib-resources; python_version < '3.12'", # MultiplexedPath is broken on earlier versions
  "click>=8.0.3,!=8.1.4", # 8.1.3 / 8.1.6 TODO type annotations tmt.cli.Context -> click.core.Context click/issues/2558
  "docutils>=0.16", # 0.16 is the current one available for RHEL9
  "fmf>=1.3.0",
@@ -413,6 +415,8 @@ builtins-ignorelist = ["help", "format", "input", "filter", "copyright", "max"]
 "pathlib.PosixPath".msg = "Use tmt._compat.pathlib.Path instead."
 "warnings.deprecated".msg = "Use tmt._compat.warnings.deprecated instead."
 "os.path".msg = "Use tmt._compat.pathlib.Path and pathlib instead."
+"importlib.metadata.entry_points".msg = "Use tmt._compat.importlib.metadata.entry_points instead."
+"importlib.readers".msg = "Use tmt._compat.importlib.readers instead."
 
 [tool.ruff.lint.isort]
 known-first-party = ["tmt"]

tests/core/env/test.sh

@@ -12,7 +12,7 @@ rlJournalStart
  rlRun -s "TMT_DEBUG=3 tmt plan show"
  rlAssertGrep "Using the 'DiscoverFmf' plugin" $rlRun_LOG
  rlRun -s "TMT_DEBUG=weird tmt plan show" 2
- rlAssertGrep "Invalid debug level" $rlRun_LOG
+ rlAssertGrep "Invalid value.*'weird' is not a valid integer" $rlRun_LOG -E
  rlPhaseEnd
 
  for execute in 'tmt'; do

tests/plugins/data/.fmf/version

@@ -0,0 +1 @@
+1

tests/plugins/data/main.fmf

@@ -0,0 +1,8 @@
+summary: Check plugin schema validation
+execute:
+ how: tmt
+provision:
+ how: example
+discover:
+ how: example
+ path: some/random/path

tests/plugins/test.sh

@@ -5,6 +5,7 @@ rlJournalStart
  rlPhaseStartSetup
  rlRun "tmp=\$(mktemp -d)" 0 "Create tmp directory"
  rlRun "cp -r $(git rev-parse --show-toplevel)/examples/plugins $tmp"
+ rlRun "cp -a data $tmp"
  rlRun "pushd $tmp"
 
  # For local development this can run already in venv, do not use venv
@@ -27,11 +28,16 @@ rlJournalStart
  rlAssertGrep "Unsupported discover method" "$rlRun_LOG"
  rlRun -s "$tmt run provision -h example --help" "2"
  rlAssertGrep "Unsupported provision method" "$rlRun_LOG"
+ rlRun -s "$tmt -r data lint --enable-check C000 --enforce-check C000" "1"
+ rlAssertGrep "fail C000 fmf node failed schema validation" "$rlRun_LOG"
+ rlAssertGrep "fail C000 key \"path\" not recognized" "$rlRun_LOG"
+ rlAssertGrep "fail C000 value of \"how\" is not" "$rlRun_LOG"
 
  # Install them to entry_point and they work now
  rlRun "pip install ./plugins"
  rlRun "$tmt run discover -h example --help"
  rlRun "$tmt run provision -h example --help"
+ rlRun -s "$tmt -r data lint --enable-check C000 --enforce-check C000"
 
  # Uninstall them
  rlRun "pip uninstall -y demo-plugins"
@@ -47,7 +53,7 @@ rlJournalStart
  rlAssertGrep "Unsupported provision method" "$rlRun_LOG"
 
  # Export variable and plugins work now
- rlRun "export TMT_PLUGINS=./plugins"
+ rlRun "export TMT_PLUGINS=./plugins/example"
  rlRun "$tmt run discover -h example --help"
  rlRun "$tmt run provision -h example --help"
  rlPhaseEnd

tmt/_compat/importlib/metadata.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+import sys
+
+if sys.version_info < (3, 10):
+ from importlib_metadata import entry_points # pyright: ignore[reportUnknownVariableType]
+else:
+ from importlib.metadata import entry_points
+
+__all__ = [
+ "entry_points",
+ ]

tmt/_compat/importlib/readers.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+import sys
+
+if sys.version_info < (3, 12):
+ from importlib_resources.readers import MultiplexedPath
+else:
+ from importlib.readers import MultiplexedPath
+
+__all__ = [
+ "MultiplexedPath",
+ ]

tmt/export/template.py

@@ -1,3 +1,4 @@
+from importlib.abc import Traversable
 from typing import Any, Optional
 
 import tmt.base
@@ -15,7 +16,7 @@ class TemplateExporter(tmt.export.ExportPlugin):
  def render_template(
  cls,
  *,
- template_filepath: Optional[Path] = None,
+ template_filepath: Optional[Traversable] = None,
  default_template_filename: str,
  keys: Optional[list[str]] = None,
  **variables: Any

tmt/log.py

@@ -108,21 +108,6 @@ def create_decolorizer(apply_colors: bool) -> Callable[[str], str]:
  return tmt.utils.remove_color
 
 
-def _debug_level_from_global_envvar() -> int:
- import tmt.utils
-
- raw_value = os.getenv('TMT_DEBUG', None)
-
- if raw_value is None:
- return 0
-
- try:
- return int(raw_value)
-
- except ValueError:
- raise tmt.utils.GeneralError(f"Invalid debug level '{raw_value}', use an integer.")
-
-
 def decide_colorization(no_color: bool, force_color: bool) -> tuple[bool, bool]:
  """
  Decide whether the output and logging should be colorized.
@@ -626,19 +611,13 @@ def apply_verbosity_options(
  else:
  self.verbosity_level = verbosity_level
 
- debug_level_from_global_envvar = _debug_level_from_global_envvar()
+ debug_level_from_option = cast(Optional[int], actual_kwargs.get('debug', None))
 
- if debug_level_from_global_envvar not in (None, 0):
- self.debug_level = debug_level_from_global_envvar
+ if debug_level_from_option is None or debug_level_from_option == 0:
+ pass
 
  else:
- debug_level_from_option = cast(Optional[int], actual_kwargs.get('debug', None))
-
- if debug_level_from_option is None or debug_level_from_option == 0:
- pass
-
- else:
- self.debug_level = debug_level_from_option
+ self.debug_level = debug_level_from_option
 
  quietness_level = actual_kwargs.get('quiet', False)
 
@@ -868,7 +847,14 @@ def get_bootstrap_logger(cls) -> 'Logger':
  # Stay away of our future main logger
  actual_logger = Logger._normalize_logger(logging.getLogger('_tmt_bootstrap'))
 
- cls._bootstrap_logger = Logger.create(actual_logger=actual_logger)
+ # The environment variables are usually handled at the click cli stage
+ # Here we enable safe parsing of those variables.
+ try:
+ debug = int(os.getenv('TMT_DEBUG', 0))
+ except ValueError:
+ debug = None
+
+ cls._bootstrap_logger = Logger.create(actual_logger=actual_logger, debug=debug)
  cls._bootstrap_logger.add_console_handler()
 
  return cls._bootstrap_logger

tmt/options.py

@@ -132,7 +132,7 @@ def option(
  '-v', '--verbose', count=True, default=0,
  help='Show more details. Use multiple times to raise verbosity.'),
  option(
- '-d', '--debug', count=True, default=0,
+ '-d', '--debug', count=True, default=0, envvar="TMT_DEBUG",
  help='Provide debugging information. Repeat to see more details.'),
  option(
  '-q', '--quiet', is_flag=True,