atex 0.9__py3-none-any.whl → 0.11__py3-none-any.whl

atex-0.11.dist-info/METADATA

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: atex
+Version: 0.11
+Summary: Ad-hoc Test EXecutor
+Project-URL: Homepage, https://github.com/RHSecurityCompliance/atex
+License-Expression: GPL-3.0-or-later
+License-File: COPYING.txt
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Requires-Dist: fmf>=1.6
+Requires-Dist: pyyaml
+Requires-Dist: urllib3<3,>=2
+Description-Content-Type: text/markdown
+
+# ATEX = Ad-hoc Test EXecutor
+
+A collections of Python APIs to provision operating systems, collect
+and execute [FMF](https://github.com/teemtee/fmf/)-style tests, gather
+and organize their results and generate reports from those results.
+
+The name comes from a (fairly unique to FMF/TMT ecosystem) approach that
+allows provisioning a pool of systems and scheduling tests on them as one would
+on an ad-hoc pool of thread/process workers - once a worker becomes free,
+it receives a test to run.  
+This is in contrast to splitting a large list of N tests onto M workers
+like N/M, which yields significant time penalties due to tests having
+very varies runtimes.
+
+Above all, this project is meant to be a toolbox, not a silver-plate solution.
+Use its Python APIs to build a CLI tool for your specific use case.  
+The CLI tool provided here is just for demonstration / testing, not for serious
+use - we want to avoid huge modular CLIs for Every Possible Scenario. That's
+the job of the Python API. Any CLI should be simple by nature.
+
+---
+
+## License
+
+Unless specified otherwise, any content within this repository is distributed
+under the GNU GPLv3 license, see the [COPYING.txt](COPYING.txt) file for more.
+
+## Environment variables
+
+- `ATEX_DEBUG_TEST`
+  - Set to `1` to print out detailed runner-related trace within the test output
+    stream (as if it was printed out by the test).
+
+## Testing this project
+
+There are some limited sanity tests provided via `pytest`, although:
+
+- Some require additional variables (ie. Testing Farm) and will ERROR
+  without them.
+- Some take a long time (ie. Testing Farm) due to system provisioning
+  taking a long time, so install `pytest-xdist` and run with a large `-n`.
+
+Currently, the recommended approach is to split the execution:
+
+```
+# synchronously, because podman CLI has concurrency issues
+pytest tests/provision/test_podman.py
+
+# in parallel, because provisioning takes a long time
+export TESTING_FARM_API_TOKEN=...
+export TESTING_FARM_COMPOSE=...
+pytest -n 20 tests/provision/test_podman.py
+
+# fast enough for synchronous execution
+pytest tests/fmf
+```
+
+## Unsorted notes
+
+TODO: codestyle from contest
+
+```
+- this is not tmt, the goal is to make a python toolbox *for* making runcontest
+  style tools easily, not to replace those tools with tmt-style CLI syntax
+
+  - the whole point is to make usecase-targeted easy-to-use tools that don't
+    intimidate users with 1 KB long command line, and runcontest is a nice example
+
+  - TL;DR - use a modular pythonic approach, not a gluetool-style long CLI
+```

atex-0.11.dist-info/RECORD

@@ -0,0 +1,45 @@
+atex/__init__.py,sha256=LdX67gprtHYeAkjLhFPKzpc7ECv2rHxUbHKDGbGXO1c,517
+atex/fmf.py,sha256=gkJXIaRO7_KvwJR-V6Tc1NVn4a9Hq7hoBLQLhxYIdbg,8834
+atex/aggregator/__init__.py,sha256=8mN-glHdzR4icKAUGO4JPodsTrLMdJoeuZsO2CTbhyU,1773
+atex/aggregator/json.py,sha256=tpoUZoZM8EMYhZKwVr4LRtgEIDjRxC11BIKVXZKYPOs,10441
+atex/cli/__init__.py,sha256=Ew2z-gC0jvOmU_DqYgXVQla3p1rTnrz64I63q52aHv4,2899
+atex/cli/fmf.py,sha256=pvj_OIp6XT_nVUwziL7-v_HNbyAtuUmb7k_Ey_KkFJc,3616
+atex/cli/libvirt.py,sha256=6tt5ANb8XBBRXOQsYPTWILThKqf-gvt5AZh5Dctg2PA,3782
+atex/cli/testingfarm.py,sha256=ovgoogmIM2TglS7iQD3liMiEYYtcykS_HRRKbltpW2I,10131
+atex/connection/__init__.py,sha256=dj8ZBcEspom7Z_UjecfLGBRNvLZ3dyGR9q19i_B4xpY,3880
+atex/connection/podman.py,sha256=1T56gh1TgbcQWpTIJHL4NaxZOI6aMg7Xp7sn6PQQyBk,1911
+atex/connection/ssh.py,sha256=9A57b9YR_HI-kIu06Asic1y__JPVXEheDZxjbG2Qcsc,13460
+atex/executor/__init__.py,sha256=XCfhi7QDELjey7N1uzhMjc46Kp1Jsd5bOCf52I27SCE,85
+atex/executor/duration.py,sha256=x06sItKOZi6XA8KszQwZGpIb1Z_L-HWqIwZKo2SDo0s,1759
+atex/executor/executor.py,sha256=toyLVQCDzfw381iEGrvOXoKPsd4SqxMZHwlDSTJGqKk,15792
+atex/executor/reporter.py,sha256=MceFmHFt0bTEClBZbRI1WnFbfMhR0e1noOzcu7gjKuQ,3403
+atex/executor/scripts.py,sha256=riJAQWsV-BFGkJwR2Dmf3R0ZRRZJs9w9iYnPpYaQNaE,5618
+atex/executor/testcontrol.py,sha256=mVrLwQUnDRfUq-5diz-80UvCWWxn1TkcBgmAKhKNb5E,12696
+atex/orchestrator/__init__.py,sha256=8Q1YknyibilXLjWRYkHm_Mr2HMm0SRw8Zv39KypeASM,2059
+atex/orchestrator/adhoc.py,sha256=QpYoPeyQzYFDBM1zgFJKMXH1RtdJixbH5whVX0OP-14,21003
+atex/orchestrator/contest.py,sha256=ADmRlsZPQx-MJ6fWHmBcJOIy3DSPnvwVheVL9Upwtg0,3703
+atex/provisioner/__init__.py,sha256=6hZxQlvTQ0yWWqCRCPqWMoYuim5wDMCcDIYHF-nIfMs,4013
+atex/provisioner/libvirt/VM_PROVISION,sha256=7pkZ-ozgTyK4qNGC-E-HUznr4IhbosWSASbB72Gknl8,2664
+atex/provisioner/libvirt/__init__.py,sha256=pKG5IpZSC2IHs5wL2ecQx_fd9AzAXEbZmDzA7RyZsfM,119
+atex/provisioner/libvirt/libvirt.py,sha256=ZKctK2B51olvWvLxz2pZ2s6LtX_7EJ43LvlyJHnI1Ho,18955
+atex/provisioner/libvirt/locking.py,sha256=AXtDyidZNmUoMmrit26g9iTHDqInrzL_RSQEoc_EAXw,5669
+atex/provisioner/libvirt/setup-libvirt.sh,sha256=oCMy9SCnbC_QuAzO2sFwvB5ui1kMQ6uviHsgdXyoFXc,2428
+atex/provisioner/podman/__init__.py,sha256=dM0JzQXWX7edtWSc0KH0cMFXAjArFn2Vme4j_ZMsdYA,138
+atex/provisioner/podman/podman.py,sha256=ztRypoakSf-jF04iER58tEMUZ4Y6AuzIpNpFXp44bB4,4997
+atex/provisioner/testingfarm/__init__.py,sha256=kZncgLGdRCR4FMaRQr2GTwJ8vjlA-24ri8JO2ueZJuw,113
+atex/provisioner/testingfarm/api.py,sha256=dlXe9brzHERawIx2UTv34u2tOSskdZtXD68-u1MnOHk,21726
+atex/provisioner/testingfarm/testingfarm.py,sha256=yvQzWat92B4UnJNZzCLI8mpAKf_QvHUKyKbjlk5123Q,8573
+atex/util/__init__.py,sha256=cWHFbtQ4mDlKe6lXyPDWRmWJOTcHDGfVuW_-GYa8hB0,1473
+atex/util/dedent.py,sha256=SEuJMtLzqz3dQ7g7qyZzEJ9VYynVlk52tQCJY-FveXo,603
+atex/util/libvirt.py,sha256=kDZmT6xLYEZkQNLZY98gJ2M48DDWXxHF8rQY9PnjB3U,660
+atex/util/log.py,sha256=KVR7ep8n5wtghsvBFCtHiPsMAQBdAmK83E_Jec5t4cU,2230
+atex/util/named_mapping.py,sha256=UBMe9TetjV-DGPhjYjJ42YtC40FVPKAAEROXl9MA5fo,4700
+atex/util/path.py,sha256=x-kXqiWCVodfZWbEwtC5A8LFvutpDIPYv2m0boZSlXU,504
+atex/util/ssh_keygen.py,sha256=9yuSl2yBV7pG3Qfsf9tossVC00nbIUrAeLdbwTykpjk,384
+atex/util/subprocess.py,sha256=_oQN8CNgGoH9GAR6nZlpujYe2HjXFBcCuIkLPw-IxJ4,2971
+atex/util/threads.py,sha256=c8hsEc-8SqJGodInorv_6JxpiHiSkGFGob4qbMmOD2M,3531
+atex-0.11.dist-info/METADATA,sha256=3fRMLBrkoRIHwbY2GheyNkrx4mNVmL_95wlxGjZsORc,3050
+atex-0.11.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+atex-0.11.dist-info/entry_points.txt,sha256=pLqJdcfeyQTgup2h6dWb6SvkHhtOl-W5Eg9zV8moK0o,39
+atex-0.11.dist-info/licenses/COPYING.txt,sha256=oEuj51jdmbXcCUy7pZ-KE0BNcJTR1okudRp5zQ0yWnU,670
+atex-0.11.dist-info/RECORD,,

{atex-0.9.dist-info → atex-0.11.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.27.0
+Generator: hatchling 1.28.0
 Root-Is-Purelib: true
 Tag: py3-none-any

atex/orchestrator/aggregator.py

@@ -1,111 +0,0 @@
-import gzip
-import json
-import shutil
-import threading
-from pathlib import Path
-
-
-class JSONAggregator:
-    """
-    Collects reported results as a GZIP-ed line-JSON and files (logs) from
-    multiple test runs under a shared directory.
-
-    Note that the aggregated JSON file *does not* use the test-based JSON format
-    described by executor/RESULTS.md - both use JSON, but are very different.
-
-    This aggergated format uses a top-level array (on each line) with a fixed
-    field order:
-
-        platform, status, test name, subtest name, files, note
-
-    All these are strings except 'files', which is another (nested) array
-    of strings.
-
-    If a field is missing in the source result, it is translated to a null
-    value.
-    """
-
-    def __init__(self, json_file, storage_dir):
-        """
-        'json_file' is a string/Path to a .json.gz file with aggregated results.
-
-        'storage_dir' is a string/Path of the top-level parent for all
-        per-platform / per-test files uploaded by tests.
-        """
-        self.lock = threading.RLock()
-        self.storage_dir = Path(storage_dir)
-        self.json_file = Path(json_file)
-        self.json_gzip_fobj = None
-
-    def open(self):
-        if self.json_file.exists():
-            raise FileExistsError(f"{self.json_file} already exists")
-        self.json_gzip_fobj = gzip.open(self.json_file, "wt", newline="\n")
-
-        if self.storage_dir.exists():
-            raise FileExistsError(f"{self.storage_dir} already exists")
-        self.storage_dir.mkdir()
-
-    def close(self):
-        if self.json_gzip_fobj:
-            self.json_gzip_fobj.close()
-            self.json_gzip_fobj = None
-
-    def __enter__(self):
-        try:
-            self.open()
-            return self
-        except Exception:
-            self.close()
-            raise
-
-    def __exit__(self, exc_type, exc_value, traceback):
-        self.close()
-
-    def ingest(self, platform, test_name, results_file, files_dir):
-        """
-        Process 'results_file' (string/Path) for reported results and append
-        them to the overall aggregated line-JSON file, recursively copying over
-        the dir structure under 'files_dir' (string/Path) under the respective
-        platform and test name in the aggregated storage dir.
-        """
-        platform_dir = self.storage_dir / platform
-        test_dir = platform_dir / test_name.lstrip("/")
-        if test_dir.exists():
-            raise FileExistsError(f"{test_dir} already exists for {test_name}")
-
-        # parse the results separately, before writing any aggregated output,
-        # to ensure that either all results from the test are ingested, or none
-        # at all (ie. if one of the result lines contains JSON errors)
-        output_lines = []
-        with open(results_file) as results_fobj:
-            for raw_line in results_fobj:
-                result_line = json.loads(raw_line)
-
-                file_names = []
-                if "testout" in result_line:
-                    file_names.append(result_line["testout"])
-                if "files" in result_line:
-                    file_names += (f["name"] for f in result_line["files"])
-
-                output_line = (
-                    platform,
-                    result_line["status"],
-                    test_name,
-                    result_line.get("name"),
-                    file_names,
-                    result_line.get("note"),
-                )
-                encoded = json.dumps(output_line, indent=None)
-                output_lines.append(encoded)
-
-        output_str = "\n".join(output_lines) + "\n"
-
-        with self.lock:
-            self.json_gzip_fobj.write(output_str)
-            self.json_gzip_fobj.flush()
-
-        Path(results_file).unlink()
-
-        platform_dir.mkdir(exist_ok=True)
-        shutil.move(files_dir, test_dir)

atex/provision/podman/__init__.py

@@ -1 +0,0 @@
-from .podman import PodmanProvisioner, PodmanRemote  # noqa: F401

atex/provision/podman/podman.py

@@ -1,274 +0,0 @@
-import os
-import time
-import enum
-import threading
-import subprocess
-
-from ... import connection, util
-from .. import Provisioner, Remote
-
-
-class PodmanRemote(Remote, connection.podman.PodmanConn):
-    """
-    Built on the official Remote API, pulling in the Connection API
-    as implemented by ManagedSSHConn.
-    """
-
-    def __init__(self, image, container, *, release_hook):
-        """
-        'image' is an image tag (used for repr()).
-
-        'container' is a podman container id / name.
-
-        'release_hook' is a callable called on .release() in addition
-        to disconnecting the connection.
-        """
-        super().__init__(container=container)
-        self.lock = threading.RLock()
-        self.image = image
-        self.container = container
-        self.release_called = False
-        self.release_hook = release_hook
-
-    def release(self):
-        with self.lock:
-            if self.release_called:
-                return
-            else:
-                self.release_called = True
-        self.release_hook(self)
-        self.disconnect()
-        util.subprocess_run(
-            ("podman", "container", "rm", "-f", "-t", "0", self.container),
-            check=False,  # ignore if it fails
-            stdout=subprocess.DEVNULL,
-        )
-
-    # not /technically/ a valid repr(), but meh
-    def __repr__(self):
-        class_name = self.__class__.__name__
-
-        if "/" in self.image:
-            image = self.image.rsplit("/",1)[1]
-        elif len(self.image) > 20:
-            image = f"{self.image[:17]}..."
-        else:
-            image = self.image
-
-        name = f"{self.container[:17]}..." if len(self.container) > 20 else self.container
-
-        return f"{class_name}({image}, {name})"
-
-
-class PodmanProvisioner(Provisioner):
-    class State(enum.Enum):
-        WAITING_FOR_PULL = enum.auto()
-        CREATING_CONTAINER = enum.auto()
-        WAITING_FOR_CREATION = enum.auto()
-        SETTING_UP_CONTAINER = enum.auto()
-        WAITING_FOR_SETUP = enum.auto()
-
-    # NOTE: this uses a single Popen process to run podman commands,
-    #       to avoid double downloads/pulls, but also to avoid SQLite errors
-    #       when creating multiple containers in parallel
-
-    def __init__(self, image, run_options=None, *, pull=True, max_systems=1):
-        """
-        'image' is a string of image tag/id to create containers from.
-        It can be a local identifier or an URL.
-
-        'run_options' is an iterable with additional CLI options passed
-        to 'podman container run'.
-
-        'pull' specifies whether to attempt 'podman image pull' on the specified
-        image tag/id before any container creation.
-
-        'max_systems' is a maximum number of containers running at any one time.
-        """
-        self.lock = threading.RLock()
-        self.image = image
-        self.run_options = run_options or ()
-        self.pull = pull
-        self.max_systems = max_systems
-
-        self.image_id = None
-        self.container_id = None
-        self.worker = None
-        self.worker_output = bytearray()
-        self.state = None
-        # created PodmanRemote instances, ready to be handed over to the user,
-        # or already in use by the user
-        self.remotes = []
-
-    @staticmethod
-    def _spawn_proc(cmd):
-        proc = util.subprocess_Popen(
-            cmd,
-            stdin=subprocess.DEVNULL,
-            stdout=subprocess.PIPE,
-            stderr=subprocess.STDOUT,
-        )
-        os.set_blocking(proc.stdout.fileno(), False)
-        return proc
-
-#    @staticmethod
-#    def _poll_proc(proc):
-#        # read from the process to un-block any kernel buffers
-#        try:
-#            out = proc.stdout.read()  # non-blocking
-#        except BlockingIOError:
-#            out = ""
-#        return (proc.poll(), out)
-
-    def _make_remote(self, container):
-        def release_hook(remote):
-            # remove from the list of remotes inside this Provisioner
-            with self.lock:
-                try:
-                    self.remotes.remove(remote)
-                except ValueError:
-                    pass
-
-        remote = PodmanRemote(
-            self.image,
-            container,
-            release_hook=release_hook,
-        )
-        self.remotes.append(remote)
-        return remote
-
-    def start(self):
-        if not self.image:
-            raise ValueError("image cannot be empty")
-
-        if not self.pull:
-            self.image_id = self.image
-            self.state = self.State.CREATING_CONTAINER
-        else:
-            self.worker = self._spawn_proc(
-                ("podman", "image", "pull", "--quiet", self.image),
-            )
-            self.state = self.State.WAITING_FOR_PULL
-
-    def stop(self):
-        with self.lock:
-            while self.remotes:
-                self.remotes.pop().release()
-            worker = self.worker
-            self.worker = None
-
-        if worker:
-            worker.kill()
-            # don"t zombie forever, return EPIPE on any attempts to write to us
-            worker.stdout.close()
-            worker.wait()
-
-    def stop_defer(self):
-        # avoid SQLite errors by removing containers sequentially
-        return self.stop
-
-    @staticmethod
-    def _nonblock_read(fobj):
-        """Return b'' if there was nothing to read, instead of None."""
-        data = fobj.read()
-        return b"" if data is None else data
-
-    def _get_remote_nonblock(self):
-        if self.state is None:
-            raise RuntimeError("the provisioner is in an invalid state")
-
-        # NOTE: these are not 'elif' statements explicitly to allow a next block
-        #       to follow a previous one (if the condition is met)
-        if self.state is self.State.WAITING_FOR_PULL:
-            self.worker_output += self._nonblock_read(self.worker.stdout)
-            rc = self.worker.poll()
-            if rc is None:
-                return None  # still running
-            elif rc != 0:
-                out = self.worker_output.decode().rstrip("\n")
-                self.worker_output.clear()
-                self.worker = None
-                self.state = None
-                raise RuntimeError(f"podman image pull failed with {rc}:\n{out}")
-            else:
-                self.image_id = self.worker_output.decode().rstrip("\n")
-                self.worker_output.clear()
-                self.worker = None
-                self.state = self.State.CREATING_CONTAINER
-
-        if self.state is self.State.CREATING_CONTAINER:
-            if len(self.remotes) < self.max_systems:
-                self.worker = self._spawn_proc(
-                    (
-                        "podman", "container", "run", "--quiet", "--detach", "--pull", "never",
-                        *self.run_options, self.image_id, "sleep", "inf",
-                    ),
-                )
-                self.state = self.State.WAITING_FOR_CREATION
-            else:
-                # too many remotes requested
-                return None
-
-        if self.state is self.State.WAITING_FOR_CREATION:
-            self.worker_output += self._nonblock_read(self.worker.stdout)
-            rc = self.worker.poll()
-            if rc is None:
-                return None  # still running
-            elif rc != 0:
-                out = self.worker_output.decode().rstrip("\n")
-                self.worker_output.clear()
-                self.worker = None
-                self.state = None
-                raise RuntimeError(f"podman run failed with {rc}:\n{out}")
-            else:
-                self.container_id = self.worker_output.decode().rstrip("\n")
-                self.worker_output.clear()
-                self.worker = None
-                self.state = self.State.SETTING_UP_CONTAINER
-
-        if self.state is self.State.SETTING_UP_CONTAINER:
-            cmd = ("dnf", "install", "-y", "-q", "--setopt=install_weak_deps=False", "rsync")
-            self.worker = self._spawn_proc(
-                ("podman", "container", "exec", self.container_id, *cmd),
-            )
-            self.state = self.State.WAITING_FOR_SETUP
-
-        if self.state is self.State.WAITING_FOR_SETUP:
-            self.worker_output += self._nonblock_read(self.worker.stdout)
-            rc = self.worker.poll()
-            if rc is None:
-                return None  # still running
-            elif rc != 0:
-                out = self.worker_output.decode().rstrip("\n")
-                self.worker_output.clear()
-                self.worker = None
-                self.state = None
-                raise RuntimeError(f"setting up failed with {rc}:\n{out}")
-            else:
-                # everything ready, give the Remote to the caller and reset
-                remote = self._make_remote(self.container_id)
-                self.worker_output.clear()
-                self.worker = None
-                self.state = self.State.CREATING_CONTAINER
-                return remote
-
-        raise AssertionError(f"reached end (invalid state {self.state}?)")
-
-    def get_remote(self, block=True):
-        if not block:
-            with self.lock:
-                return self._get_remote_nonblock()
-        else:
-            while True:
-                with self.lock:
-                    if remote := self._get_remote_nonblock():
-                        return remote
-                time.sleep(0.1)
-
-    # not /technically/ a valid repr(), but meh
-    def __repr__(self):
-        class_name = self.__class__.__name__
-        return (
-            f"{class_name}({self.image}, {len(self.remotes)}/{self.max_systems} remotes, "
-            f"{hex(id(self))})"
-        )