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

atex/util/log.py

@@ -1,76 +1,71 @@
-import inspect
+import os
 import logging
-from pathlib import Path
+import inspect
 
 _logger = logging.getLogger("atex")
 
+# which functions to skip when determining the logger function caller;
+# typically, these are wrappers and we want to see their caller in the trace
+# instead of them
+#
+# ( file basename , qualname )
+# where qualname is '<module>' or 'funcname' or 'Classname.funcname'
+skip_levels = {
+    ("subprocess.py", "subprocess_run"),
+    ("subprocess.py", "subprocess_output"),
+    ("subprocess.py", "subprocess_Popen"),
+    ("subprocess.py", "subprocess_stream"),
+    ("subprocess.py", "subprocess_log"),
 
-def in_debug_mode():
-    """
-    Return True if the root logger is using the DEBUG (or more verbose) level.
-    """
-    # TODO: use _logger.isEnabledFor() ?
-    root_level = logging.getLogger().level
-    return root_level > 0 and root_level <= logging.DEBUG
+    ("podman.py", "PodmanConnection.cmd"),
+    ("podman.py", "PodmanConnection.rsync"),
 
+    ("ssh.py", "StatelessSSHConnection.cmd"),
+    ("ssh.py", "StatelessSSHConnection.rsync"),
+    ("ssh.py", "ManagedSSHConnection.forward"),
+    ("ssh.py", "ManagedSSHConnection.cmd"),
+    ("ssh.py", "ManagedSSHConnection.rsync"),
+}
 
-def _format_msg(msg, *, skip_frames=0):
-    stack = inspect.stack()
-    if len(stack)-1 <= skip_frames:
-        raise SyntaxError("skip_frames exceeds call stack (frame count)")
-    stack = stack[skip_frames+1:]
 
-    # bottom of the stack, or runpy executed module
-    for frame_info in stack:
-        if frame_info.function == "<module>":
+def _log_msg(logger_func, *args, stacklevel=1, **kwargs):
+    # inspect.stack() is MUCH slower
+    caller = inspect.currentframe().f_back.f_back
+    extra_levels = 2  # skip this func and the debug/info/warning parent
+    while caller.f_back:
+        code = caller.f_code
+        # pathlib is much slower
+        basename = os.path.basename(code.co_filename)  # noqa: PTH119
+        qualname = code.co_qualname
+        if (basename, qualname) in skip_levels:
+            extra_levels += 1
+            caller = caller.f_back
+        else:
             break
-    module = frame_info
-
-    # last (topmost) function that isn't us
-    parent = stack[0]
-    function = parent.function
-
-    # if the function has 'self' and it looks like a class instance,
-    # prepend it to the function name
-    argvals = inspect.getargvalues(parent.frame)
-    if argvals.args:
-        if argvals.args[0] == "self":
-            self = argvals.locals["self"]
-            if hasattr(self, "__class__") and inspect.isclass(self.__class__):
-                function = f"{self.__class__.__name__}.{function}"
-        elif argvals.args[0] == "cls":
-            cls = argvals.locals["cls"]
-            if inspect.isclass(cls):
-                function = f"{cls.__name__}.{function}"
-
-    # don't report module name of a function if it's the same as running module
-    if parent.filename != module.filename:
-        parent_modname = parent.frame.f_globals["__name__"]
-        # avoid everything having the package name prefixed
-        parent_modname = parent_modname.partition(".")[2] or parent_modname
-        return f"{parent_modname}.{function}:{parent.lineno}: {msg}"
-    elif parent.function != "<module>":
-        return f"{function}:{parent.lineno}: {msg}"
-    else:
-        return f"{Path(parent.filename).name}:{parent.lineno}: {msg}"
-
-
-def debug(msg, *, skip_frames=0):
-    if in_debug_mode():
-        _logger.debug(_format_msg(msg, skip_frames=skip_frames+1))
-    else:
-        _logger.debug(msg)
-
-
-def info(msg, *, skip_frames=0):
-    if in_debug_mode():
-        _logger.info(_format_msg(msg, skip_frames=skip_frames+1))
-    else:
-        _logger.info(msg)
-
-
-def warning(msg, *, skip_frames=0):
-    if in_debug_mode():
-        _logger.warning(_format_msg(msg, skip_frames=skip_frames+1))
-    else:
-        _logger.warning(msg)
+    return logger_func(*args, stacklevel=stacklevel+extra_levels, **kwargs)
+
+
+def warning(*args, **kwargs):
+    return _log_msg(_logger.warning, *args, **kwargs)
+
+
+def info(*args, **kwargs):
+    return _log_msg(_logger.info, *args, **kwargs)
+
+
+def debug(*args, **kwargs):
+    return _log_msg(_logger.debug, *args, **kwargs)
+
+
+# add a log level more verbose than logging.DEBUG, for verbose command
+# outputs, big JSON / XML printouts, and other outputs unsuitable for
+# large parallel runs; to be used in targeted debugging
+#
+# logging.DEBUG is 10, and programs tend to add TRACE as 5, so be somewhere
+# in between
+EXTRADEBUG = 8
+logging.addLevelName(EXTRADEBUG, "EXTRADEBUG")
+
+
+def extradebug(*args, **kwargs):
+    return _log_msg(_logger.log, EXTRADEBUG, *args, **kwargs)

atex/util/subprocess.py

@@ -1,52 +1,86 @@
 import subprocess
 
-from .log import debug
+from .log import debug, extradebug
 
 
-def subprocess_run(cmd, *, skip_frames=0, **kwargs):
+def subprocess_run(cmd, **kwargs):
     """
     A simple wrapper for the real subprocess.run() that logs the command used.
     """
     # when logging, skip current stack frame - report the place we were called
     # from, not util.subprocess_run itself
-    debug(f"running: {cmd}", skip_frames=skip_frames+1)
+    debug(f"running: '{cmd}' with {kwargs=}")
     return subprocess.run(cmd, **kwargs)
 
 
-def subprocess_output(cmd, *, skip_frames=0, check=True, text=True, **kwargs):
+def subprocess_output(cmd, *, check=True, text=True, **kwargs):
     """
     A wrapper simulating subprocess.check_output() via a modern .run() API.
     """
-    debug(f"running: {cmd}", skip_frames=skip_frames+1)
+    debug(f"running: '{cmd}' with {check=}, {text=} and {kwargs=}")
     proc = subprocess.run(cmd, check=check, text=text, stdout=subprocess.PIPE, **kwargs)
     return proc.stdout.rstrip("\n") if text else proc.stdout
 
 
-def subprocess_Popen(cmd, *, skip_frames=0, **kwargs):  # noqa: N802
+def subprocess_Popen(cmd, **kwargs):  # noqa: N802
     """
     A simple wrapper for the real subprocess.Popen() that logs the command used.
     """
-    debug(f"running: {cmd}", skip_frames=skip_frames+1)
+    debug(f"running: '{cmd}' with {kwargs=}")
     return subprocess.Popen(cmd, **kwargs)
 
 
-def subprocess_stream(cmd, *, check=False, skip_frames=0, **kwargs):
+def subprocess_stream(cmd, *, stream="stdout", check=False, input=None, **kwargs):
     """
     Run 'cmd' via subprocess.Popen() and return an iterator over any lines
     the command outputs on stdout, in text mode.
 
+    The 'stream' is a subprocess.Popen attribute (either 'stdout' or 'stderr')
+    to read from.
+    To capture both stdout and stderr as yielded lines, use 'stream="stdout"'
+    and pass an additional 'stderr=subprocess.STDOUT'.
+
     With 'check' set to True, raise a CalledProcessError if the 'cmd' failed.
 
-    To capture both stdout and stderr as yielded lines, use subprocess.STDOUT.
+    Similarly, 'input' simulates the 'input' arg of subprocess.run().
+    Note that the input is written to stdin of the process *before* any outputs
+    are streamed, so it should be sufficiently small and/or not cause a deadlock
+    with the process waiting for outputs to be read before consuming more input.
+    Use 'stdin=subprocess.PIPE' and write to it manually if you need more.
     """
-    debug(f"running: {cmd}", skip_frames=skip_frames+1)
-    proc = subprocess.Popen(cmd, stdout=subprocess.PIPE, text=True, **kwargs)
+    all_kwargs = {
+        "text": True,
+        stream: subprocess.PIPE,
+    }
+    if input is not None:
+        all_kwargs["stdin"] = subprocess.PIPE
+    all_kwargs |= kwargs
+
+    debug(f"running: '{cmd}' with {all_kwargs=}")
+    proc = subprocess.Popen(cmd, **all_kwargs)
 
     def generate_lines():
-        for line in proc.stdout:
+        if input is not None:
+            proc.stdin.write(input)
+            proc.stdin.close()
+        line_stream = getattr(proc, stream)
+        for line in line_stream:
             yield line.rstrip("\n")
         code = proc.wait()
         if code > 0 and check:
             raise subprocess.CalledProcessError(cmd=cmd, returncode=code)
 
     return (proc, generate_lines())
+
+
+def subprocess_log(cmd, **kwargs):
+    """
+    A wrapper to stream every (text) line output from the process to the
+    logging module.
+
+    Uses subprocess_stream() to gather the lines.
+    """
+    debug(f"running: '{cmd}' with {kwargs=}")
+    _, lines = subprocess_stream(cmd, **kwargs)
+    for line in lines:
+        extradebug(line)

atex/util/threads.py

@@ -97,3 +97,10 @@ class ThreadQueue:
                 except KeyError:
                     break
             thread.join()
+
+    def qsize(self):
+        """
+        Return the amount of elements .get() can retrieve before it raises
+        queue.Empty.
+        """
+        return self.queue.qsize()

atex-0.10.dist-info/METADATA

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: atex
+Version: 0.10
+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.10.dist-info/RECORD

@@ -0,0 +1,44 @@
+atex/__init__.py,sha256=LdX67gprtHYeAkjLhFPKzpc7ECv2rHxUbHKDGbGXO1c,517
+atex/fmf.py,sha256=gkJXIaRO7_KvwJR-V6Tc1NVn4a9Hq7hoBLQLhxYIdbg,8834
+atex/aggregator/__init__.py,sha256=uNnYSyDGXjknxckI8MFfl-C8_gin8FwQchiq-UOyP6I,1744
+atex/aggregator/json.py,sha256=x1zim9O2olzBh185NYWo5N96fixB2oxCamoOZwmgR9w,3330
+atex/cli/__init__.py,sha256=X5XxkDEDXE4tJAjwt5ShRHCFTXDK-2zvxQ34opmueUc,2768
+atex/cli/fmf.py,sha256=HfbTgFbCwK4Nuyq6vtGutcq_4-4kj-tmoqzXUn3AYtY,3573
+atex/cli/libvirt.py,sha256=6tt5ANb8XBBRXOQsYPTWILThKqf-gvt5AZh5Dctg2PA,3782
+atex/cli/testingfarm.py,sha256=HGlqrkhanUMo2CqKxmM3ACgptWtxm0gICyEGf7O6Qc0,9078
+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=JLFR9cZjSlUdAlAlLct6WuzmYbtjGtSobxvsToQum6M,15738
+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=GnvHLlCHeJ_nQ8doEjMuDzqmu4XZorI7ZzOtG_C08tU,18451
+atex/provisioner/__init__.py,sha256=2eepmEznq94tbam9VSWbsGFrZZpWeNSVlsTczGxjNuQ,4667
+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=rtxowv5DpgcWsGRXYF29n6S9x_cgXRVgqY41DiFu920,18431
+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=UcMN61nBr3wqEd5KSR5Xhv1-TS7nSPFvk2byb6PdIs8,21811
+atex/provisioner/testingfarm/testingfarm.py,sha256=OI-a99xALaiYf-y5037WFVxY1g2H2y1xEKxHBdUQvfg,8271
+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=PQBxcQJPapP1ZLO4LqENyrxxCbNAxtJDNNlBV5DcD9k,2953
+atex/util/threads.py,sha256=c8hsEc-8SqJGodInorv_6JxpiHiSkGFGob4qbMmOD2M,3531
+atex-0.10.dist-info/METADATA,sha256=evOBYvVboY2T8eGrAKy64UpyeuFKSMLGz8pUz8Sstm8,3050
+atex-0.10.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+atex-0.10.dist-info/entry_points.txt,sha256=pLqJdcfeyQTgup2h6dWb6SvkHhtOl-W5Eg9zV8moK0o,39
+atex-0.10.dist-info/licenses/COPYING.txt,sha256=oEuj51jdmbXcCUy7pZ-KE0BNcJTR1okudRp5zQ0yWnU,670
+atex-0.10.dist-info/RECORD,,

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))})"
-        )