atex 0.13__py3-none-any.whl → 0.15__py3-none-any.whl

atex/orchestrator/__init__.py

@@ -1,3 +1,4 @@
+import abc as _abc
 import importlib as _importlib
 import pkgutil as _pkgutil
 import time as _time
@@ -14,16 +15,16 @@ class Orchestrator:
     TODO: more description
     """
 
+    @_abc.abstractmethod
     def serve_once(self):
         """
         Run the orchestration logic, processing any outstanding requests
         (for provisioning, new test execution, etc.) and returning once these
         are taken care of.
 
-        Returns True to indicate that it should be called again by the user
-        (more work to be done), False once all testing is concluded.
+        Returns `True` to indicate that it should be called again by the user
+        (more work to be done), `False` once all testing is concluded.
         """
-        raise NotImplementedError(f"'serve_once' not implemented for {self.__class__.__name__}")
 
     def serve_forever(self):
         """
@@ -32,18 +33,18 @@ class Orchestrator:
         while self.serve_once():
             _time.sleep(1)
 
+    @_abc.abstractmethod
     def start(self):
         """
         Start the Orchestrator instance, opening any files / allocating
         resources as necessary.
         """
-        raise NotImplementedError(f"'start' not implemented for {self.__class__.__name__}")
 
+    @_abc.abstractmethod
     def stop(self):
         """
         Stop the Orchestrator instance, freeing all allocated resources.
         """
-        raise NotImplementedError(f"'stop' not implemented for {self.__class__.__name__}")
 
     def __enter__(self):
         try:

atex/orchestrator/adhoc.py

@@ -1,3 +1,4 @@
+import logging
 import tempfile
 import concurrent.futures
 from pathlib import Path
@@ -5,6 +6,8 @@ from pathlib import Path
 from .. import util, executor
 from . import Orchestrator, OrchestratorError
 
+logger = logging.getLogger("atex.orchestrator.adhoc")
+
 
 class FailedSetupError(OrchestratorError):
     pass
@@ -62,32 +65,32 @@ class AdHocOrchestrator(Orchestrator):
         max_remotes=1, max_spares=0, max_failed_setups=10, env=None,
     ):
         """
-        'platform' is a string with platform name.
+        - `platform` is a string with platform name.
 
-        'fmf_tests' is a class FMFTests instance of the tests to run.
+        - `fmf_tests` is a class FMFTests instance of the tests to run.
 
-        'provisioners' is an iterable of class Provisioner instances.
+        - `provisioners` is an iterable of class Provisioner instances.
 
-        'aggregator' is a class CSVAggregator instance.
+        - `aggregator` is a class Aggregator instance.
 
-        'tmp_dir' is a string/Path to a temporary directory, to be used for
-        storing per-test results and uploaded files before being ingested
-        by the aggregator. Can be safely shared by Orchestrator instances.
+        - `tmp_dir` is a string/Path to a temporary directory, to be used for
+          storing per-test results and uploaded files before being ingested
+          by the aggregator. Can be safely shared by Orchestrator instances.
 
-        'max_remotes' is how many Remotes to hold reserved at any given time,
-        eg. how many tests to run in parallel. Clamped to the number of
-        to-be-run tests given as 'fmf_tests'.
+        - `max_remotes` is how many Remotes to hold reserved at any given time,
+          eg. how many tests to run in parallel. Clamped to the number of
+          to-be-run tests given as `fmf_tests`.
 
-        'max_spares' is how many set-up Remotes to hold reserved and unused,
-        ready to replace a Remote destroyed by test. Values above 0 greatly
-        speed up test reruns as Remote reservation happens asynchronously
-        to test execution. Spares are reserved on top of 'max_remotes'.
+        - `max_spares` is how many set-up Remotes to hold reserved and unused,
+          ready to replace a Remote destroyed by test. Values above 0 greatly
+          speed up test reruns as Remote reservation happens asynchronously
+          to test execution. Spares are reserved on top of `max_remotes`.
 
-        'max_failed_setups' is an integer of how many times an Executor's
-        plan setup (uploading tests, running prepare scripts, etc.) may fail
-        before FailedSetupError is raised.
+        - `max_failed_setups` is an integer of how many times an Executor's
+          plan setup (uploading tests, running prepare scripts, etc.) may fail
+          before FailedSetupError is raised.
 
-        'env' is a dict of extra environment variables to pass to Executor.
+        - `env` is a dict of extra environment variables to pass to Executor.
         """
         if not fmf_tests.tests:
             raise ValueError("'fmf_tests' has no tests (bad discover params?)")
@@ -118,15 +121,17 @@ class AdHocOrchestrator(Orchestrator):
 
     def _run_new_test(self, info):
         """
-        'info' can be either
+        `info` can be either
+
           - SetupInfo instance with Remote/Executor to run the new test.
+
           - FinishedInfo instance of a previously executed test
             (reusing Remote/Executor for a new test).
         """
         next_test_name = self.next_test(self.to_run, self.fmf_tests.tests, info)
         assert next_test_name in self.to_run, "next_test() returned valid test name"
 
-        util.info(f"{info.remote}: starting '{next_test_name}'")
+        logger.info(f"{info.remote}: starting '{next_test_name}'")
 
         self.to_run.remove(next_test_name)
 
@@ -155,14 +160,14 @@ class AdHocOrchestrator(Orchestrator):
 
     def _process_finished_test(self, finfo):
         """
-        'finfo' is a FinishedInfo instance.
+        `finfo` is a FinishedInfo instance.
         """
         test_data = self.fmf_tests.tests[finfo.test_name]
         remote_with_test = f"{finfo.remote}: '{finfo.test_name}'"
 
         if not self.was_successful(finfo, test_data) and self.should_be_rerun(finfo, test_data):
             # re-run the test
-            util.info(f"{remote_with_test} failed, re-running")
+            logger.info(f"{remote_with_test} failed, re-running")
             self.to_run.add(finfo.test_name)
         else:
             # ingest the result
@@ -170,7 +175,7 @@ class AdHocOrchestrator(Orchestrator):
             # a condition just in case Executor code itself threw an exception
             # and didn't even report the fallback 'infra' result
             if finfo.results is not None and finfo.files is not None:
-                util.info(f"{remote_with_test} completed, ingesting result")
+                logger.info(f"{remote_with_test} completed, ingesting result")
 
                 def ingest_and_cleanup(ingest, args, cleanup):
                     ingest(*args)
@@ -201,7 +206,7 @@ class AdHocOrchestrator(Orchestrator):
         # if there are still tests to be run and the last test was not
         # destructive, just run a new test on it
         if self.to_run and not (finfo.exception or self.destructive(finfo, test_data)):
-            util.debug(f"{remote_with_test} was non-destructive, running next test")
+            logger.debug(f"{remote_with_test} was non-destructive, running next test")
             self._run_new_test(finfo)
             return
 
@@ -211,7 +216,7 @@ class AdHocOrchestrator(Orchestrator):
         if self.remotes_requested >= len(self.to_run):
             # we have enough remotes in the pipe to run every test,
             # we don't need a new one - just release the current one
-            util.debug(f"{finfo.remote} no longer useful, releasing it")
+            logger.debug(f"{finfo.remote} no longer useful, releasing it")
             self.release_queue.start_thread(
                 finfo.remote.release,
                 remote=finfo.remote,
@@ -219,7 +224,7 @@ class AdHocOrchestrator(Orchestrator):
         else:
             # we need more remotes and the last test was destructive,
             # get a new one and let serve_once() run a test later
-            util.debug(f"{remote_with_test} was destructive, getting a new Remote")
+            logger.debug(f"{remote_with_test} was destructive, getting a new Remote")
             self.release_queue.start_thread(
                 finfo.remote.release,
                 remote=finfo.remote,
@@ -227,14 +232,6 @@ class AdHocOrchestrator(Orchestrator):
             finfo.provisioner.provision(1)
 
     def serve_once(self):
-        """
-        Run the orchestration logic, processing any outstanding requests
-        (for provisioning, new test execution, etc.) and returning once these
-        are taken care of.
-
-        Returns True to indicate that it should be called again by the user
-        (more work to be done), False once all testing is concluded.
-        """
         # all done
         if not self.to_run and not self.running_tests:
             return False
@@ -282,12 +279,12 @@ class AdHocOrchestrator(Orchestrator):
                     remote=sinfo.remote,
                 )
                 if (retries_left := self.failed_setups_left) > 0:
-                    util.warning(f"{msg}, re-trying ({retries_left} setup retries left)")
+                    logger.warning(f"{msg}, re-trying ({retries_left} setup retries left)")
                     self.failed_setups_left -= 1
                     sinfo.provisioner.provision(1)
                     self.remotes_requested += 1
                 else:
-                    util.warning(f"{msg}, setup retries exceeded, giving up")
+                    logger.warning(f"{msg}, setup retries exceeded, giving up")
                     raise FailedSetupError("setup retries limit exceeded, broken infra?")
             else:
                 self._run_new_test(sinfo)
@@ -300,7 +297,7 @@ class AdHocOrchestrator(Orchestrator):
                     treturn = self.setup_queue.get_raw(block=False)
                 except util.ThreadQueue.Empty:
                     break
-                util.debug(f"releasing extraneous set-up {treturn.sinfo.remote}")
+                logger.debug(f"releasing extraneous set-up {treturn.sinfo.remote}")
                 self.release_queue.start_thread(
                     treturn.sinfo.remote.release,
                     remote=treturn.sinfo.remote,
@@ -322,7 +319,7 @@ class AdHocOrchestrator(Orchestrator):
                     target_args=(sinfo,),
                     sinfo=sinfo,
                 )
-                util.info(f"{provisioner}: running setup on new {remote}")
+                logger.info(f"{provisioner}: running setup on new {remote}")
 
         # gather returns from Remote.release() functions - check for exceptions
         # thrown, re-report them as warnings as they are not typically critical
@@ -335,9 +332,9 @@ class AdHocOrchestrator(Orchestrator):
             else:
                 if treturn.exception:
                     exc_str = f"{type(treturn.exception).__name__}({treturn.exception})"
-                    util.warning(f"{treturn.remote} release failed: {exc_str}")
+                    logger.warning(f"{treturn.remote} release failed: {exc_str}")
                 else:
-                    util.debug(f"{treturn.remote} release completed")
+                    logger.debug(f"{treturn.remote} release completed")
 
         # gather returns from Aggregator.ingest() calls - check for exceptions
         while True:
@@ -348,9 +345,9 @@ class AdHocOrchestrator(Orchestrator):
             else:
                 if treturn.exception:
                     exc_str = f"{type(treturn.exception).__name__}({treturn.exception})"
-                    util.warning(f"'{treturn.test_name}' ingesting failed: {exc_str}")
+                    logger.warning(f"'{treturn.test_name}' ingesting failed: {exc_str}")
                 else:
-                    util.debug(f"'{treturn.test_name}' ingesting completed")
+                    logger.debug(f"'{treturn.test_name}' ingesting completed")
 
         return True
 
@@ -388,9 +385,9 @@ class AdHocOrchestrator(Orchestrator):
             else:
                 if treturn.exception:
                     exc_str = f"{type(treturn.exception).__name__}({treturn.exception})"
-                    util.warning(f"'{treturn.test_name}' ingesting failed: {exc_str}")
+                    logger.warning(f"'{treturn.test_name}' ingesting failed: {exc_str}")
                 else:
-                    util.debug(f"'{treturn.test_name}' ingesting completed")
+                    logger.debug(f"'{treturn.test_name}' ingesting completed")
         self.ingest_queue.join()
 
         # stop all provisioners, also releasing all remotes
@@ -406,7 +403,7 @@ class AdHocOrchestrator(Orchestrator):
         """
         Set up a newly acquired class Remote instance for test execution.
 
-        'sinfo' is a SetupInfo instance with the (fully connected) remote.
+        - `sinfo` is a SetupInfo instance with the (fully connected) remote.
         """
         sinfo.executor.start()
         sinfo.executor.upload_tests()
@@ -421,18 +418,20 @@ class AdHocOrchestrator(Orchestrator):
         """
         Return a test name (string) to be executed next.
 
-        'to_run' is a set of test names to pick from. The returned test name
-        must be chosen from this set.
+        - `to_run` is a set of test names to pick from. The returned test name
+          must be chosen from this set.
 
-        'tests' is a dict indexed by test name (string), with values being
-        fully resolved fmf test metadata (dicts) of all possible tests.
+        - `tests` is a dict indexed by test name (string), with values being
+          fully resolved fmf test metadata (dicts) of all possible tests.
+
+        - `previous` can be either
 
-        'previous' can be either
           - Orchestrator.SetupInfo instance (first test to be run)
+
           - Orchestrator.FinishedInfo instance (previous executed test)
 
         This method must not modify any of its arguments, it must treat them
-        as read-only, eg. don't remove the returned test name from 'to_run'.
+        as read-only, eg. don't remove the returned test name from `to_run`.
         """
         # default to simply picking any available test
         return next(iter(to_run))
@@ -444,9 +443,9 @@ class AdHocOrchestrator(Orchestrator):
         to a class Remote instance, indicating that the Remote instance
         should not be used for further test execution.
 
-        'info' is Orchestrator.FinishedInfo namedtuple of the test.
+        - `info` is Orchestrator.FinishedInfo namedtuple of the test.
 
-        'test_data' is a dict of fully resolved fmf test metadata of that test.
+        - `test_data` is a dict of fully resolved fmf test metadata of that test.
         """
         # if Executor ended with an exception (ie. duration exceeded),
         # consider the test destructive
@@ -464,21 +463,21 @@ class AdHocOrchestrator(Orchestrator):
     def was_successful(info, test_data):  # noqa: ARG004
         """
         Return a boolean result whether a finished test was successful.
-        Returning False might cause it to be re-run (per should_be_rerun()).
+        Returning `False` might cause it to be re-run (per `should_be_rerun()`).
 
-        'info' is Orchestrator.FinishedInfo namedtuple of the test.
+        - `info` is Orchestrator.FinishedInfo namedtuple of the test.
 
-        'test_data' is a dict of fully resolved fmf test metadata of that test.
+        - `test_data` is a dict of fully resolved fmf test metadata of that test.
         """
         remote_with_test = f"{info.remote}: '{info.test_name}'"
         # executor (or test) threw exception
         if info.exception:
             exc_str = f"{type(info.exception).__name__}({info.exception})"
-            util.info(f"{remote_with_test} threw {exc_str} during test runtime")
+            logger.info(f"{remote_with_test} threw {exc_str} during test runtime")
             return False
         # the test exited as non-0
         if info.exit_code != 0:
-            util.info(f"{remote_with_test} exited with non-zero: {info.exit_code}")
+            logger.info(f"{remote_with_test} exited with non-zero: {info.exit_code}")
             return False
         # otherwise we good
         return True
@@ -490,9 +489,9 @@ class AdHocOrchestrator(Orchestrator):
         that another execution attempt might succeed, due to race conditions
         in the test or other non-deterministic factors.
 
-        'info' is Orchestrator.FinishedInfo namedtuple of the test.
+        - `info` is Orchestrator.FinishedInfo namedtuple of the test.
 
-        'test_data' is a dict of fully resolved fmf test metadata of that test.
+        - `test_data` is a dict of fully resolved fmf test metadata of that test.
         """
         # never rerun by default
         return False

atex/orchestrator/contest.py

@@ -1,8 +1,11 @@
+import logging
 import collections
 
 from .. import util
 from .adhoc import AdHocOrchestrator
 
+logger = logging.getLogger("atex.provisioner.contest")
+
 
 # copy/pasted from the Contest repo, lib/virt.py
 def calculate_guest_tag(tags):
@@ -21,7 +24,7 @@ def calculate_guest_tag(tags):
 class ContestOrchestrator(AdHocOrchestrator):
     """
     Orchestrator for the Contest test suite:
-        https://github.com/RHSecurityCompliance/contest
+    https://github.com/RHSecurityCompliance/contest
 
     Includes SCAP content upload via rsync and other Contest-specific
     optimizations (around VM snapshots and scheduling).
@@ -30,11 +33,12 @@ class ContestOrchestrator(AdHocOrchestrator):
 
     def __init__(self, *args, content_dir, max_reruns=1, **kwargs):
         """
-        'content_dir' is a filesystem path to ComplianceAsCode/content local
-        directory, to be uploaded to the tested systems.
+        - `content_dir` is a filesystem path to ComplianceAsCode/content local
+          directory, to be uploaded to the tested systems.
 
-        'max_reruns' is an integer of how many times to re-try running a failed
-        test (which exited with non-0 or caused an Executor exception).
+        - `max_reruns` is an integer of how many times to re-try running
+          a failed test (which exited with non-0 or caused an Executor
+          exception).
         """
         super().__init__(*args, **kwargs)
         self.content_dir = content_dir
@@ -59,9 +63,9 @@ class ContestOrchestrator(AdHocOrchestrator):
         if type(previous) is AdHocOrchestrator.SetupInfo:
             for next_name in to_run:
                 next_tags = all_tests[next_name].get("tag", ())
-                util.debug(f"considering next_test for destructivity: {next_name}")
+                logger.debug(f"considering next_test for destructivity: {next_name}")
                 if "destructive" in next_tags:
-                    util.debug(f"chosen next_test: {next_name}")
+                    logger.debug(f"chosen next_test: {next_name}")
                     return next_name
 
         # previous test was run and finished non-destructively,
@@ -69,15 +73,15 @@ class ContestOrchestrator(AdHocOrchestrator):
         # as the previous one, allowing snapshot reuse by Contest
         elif type(previous) is AdHocOrchestrator.FinishedInfo:
             finished_tags = all_tests[previous.test_name].get("tag", ())
-            util.debug(f"previous finished test on {previous.remote}: {previous.test_name}")
+            logger.debug(f"previous finished test on {previous.remote}: {previous.test_name}")
             # if Guest tag is None, don't bother searching
             if finished_guest_tag := calculate_guest_tag(finished_tags):
                 for next_name in to_run:
-                    util.debug(f"considering next_test with tags {finished_tags}: {next_name}")
+                    logger.debug(f"considering next_test with tags {finished_tags}: {next_name}")
                     next_tags = all_tests[next_name].get("tag", ())
                     next_guest_tag = calculate_guest_tag(next_tags)
                     if next_guest_tag and finished_guest_tag == next_guest_tag:
-                        util.debug(f"chosen next_test: {next_name}")
+                        logger.debug(f"chosen next_test: {next_name}")
                         return next_name
 
         # fallback to the default next_test()
@@ -108,7 +112,7 @@ class ContestOrchestrator(AdHocOrchestrator):
         remote_with_test = f"{info.remote}: '{info.test_name}'"
 
         reruns_left = self.reruns[info.test_name]
-        util.info(f"{remote_with_test}: {reruns_left} reruns left")
+        logger.info(f"{remote_with_test}: {reruns_left} reruns left")
         if reruns_left > 0:
             self.reruns[info.test_name] -= 1
             return True

atex/provisioner/__init__.py

@@ -1,3 +1,4 @@
+import abc as _abc
 import importlib as _importlib
 import pkgutil as _pkgutil
 
@@ -10,20 +11,27 @@ class Remote(_connection.Connection):
     a Connection-like API in addition to system management helpers.
 
     An instance of Remote is typically prepared by a Provisioner and returned
-    to the caller for use and an eventual .release().
+    to the caller for use and an eventual `.release()`.
 
     Also note that Remote can be used via Context Manager, but does not
-    do automatic .release(), the manager only handles the built-in Connection.
+    do automatic `.release()`, the manager only handles the built-in Connection.
     The intention is for a Provisioner to run via its own Contest Manager and
     release all Remotes upon exit.
-    If you need automatic release of one Remote, use a try/finally block.
+
+    If you need automatic release of one Remote, use a try/finally block, ie.
+
+        try:
+            remote.cmd(...)
+            ...
+        finally:
+            remote.release()
     """
 
+    @_abc.abstractmethod
     def release(self):
         """
         Release (de-provision) the remote resource.
         """
-        raise NotImplementedError(f"'release' not implemented for {self.__class__.__name__}")
 
 
 class Provisioner:
@@ -31,12 +39,13 @@ class Provisioner:
     A remote resource (machine/system) provider.
 
     The idea is to request machines (a.k.a. Remotes, or class Remote instances)
-    to be reserved via a non-blocking .provision() and for them to be retrieved
-    through blocking / non-blocking .get_remote() when they become available.
+    to be reserved via a non-blocking `.provision()` and for them to be
+    retrieved through blocking / non-blocking `.get_remote()` when they
+    become available.
 
-    Each Remote has its own .release() for freeing (de-provisioning) it once
+    Each Remote has its own `.release()` for freeing (de-provisioning) it once
     the user doesn't need it anymore. The Provisioner does this automatically
-    to all Remotes during .stop() or context manager exit.
+    to all Remotes during `.stop()` or Context Manager exit.
 
         p = Provisioner()
         p.start()
@@ -52,42 +61,42 @@ class Provisioner:
             remote2 = p.get_remote()
             ...
 
-    Note that .provision() is a hint expressed by the caller, not a guarantee
-    that .get_remote() will ever return a Remote. Ie. the caller can call
-    .provision(count=math.inf) to receive as many remotes as the Provisioner
+    Note that `.provision()` is a hint expressed by the caller, not a guarantee
+    that `.get_remote()` will ever return a Remote. Ie. the caller can call
+    `.provision(count=math.inf)` to receive as many remotes as the Provisioner
     can possibly supply.
     """
 
+    @_abc.abstractmethod
     def provision(self, count=1):
         """
-        Request that 'count' machines be provisioned (reserved) for use,
-        to be returned at a later point by .get_remote().
+        Request that `count` machines be provisioned (reserved) for use,
+        to be returned at a later point by `.get_remote()`.
         """
-        raise NotImplementedError(f"'provision' not implemented for {self.__class__.__name__}")
 
+    @_abc.abstractmethod
     def get_remote(self, block=True):
         """
-        Return a connected class Remote instance of a previously .provision()ed
-        remote system.
+        Return a connected class Remote instance of a previously
+        `.provision()`ed remote system.
 
-        If 'block' is True, wait for the Remote to be available and connected,
-        otherwise return None if there is none available yet.
+        - If `block` is True, wait for the Remote to be available and connected,
+          otherwise return None if there is none available yet.
         """
-        raise NotImplementedError(f"'get_remote' not implemented for {self.__class__.__name__}")
 
+    @_abc.abstractmethod
     def start(self):
         """
         Start the Provisioner instance, start any provisioning-related
         processes that lead to systems being reserved.
         """
-        raise NotImplementedError(f"'start' not implemented for {self.__class__.__name__}")
 
+    @_abc.abstractmethod
     def stop(self):
         """
         Stop the Provisioner instance, freeing all reserved resources,
-        calling .release() on all Remote instances that were created.
+        calling `.release()` on all Remote instances that were created.
         """
-        raise NotImplementedError(f"'stop' not implemented for {self.__class__.__name__}")
 
     def __enter__(self):
         try: