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

atex/executor/__init__.py

@@ -2,21 +2,18 @@ class ExecutorError(Exception):
     """
     Raised by class Executor.
     """
-    pass
 
 
 class TestSetupError(ExecutorError):
     """
     Raised when the preparation for test execution (ie. pkg install) fails.
     """
-    pass
 
 
 class TestAbortedError(ExecutorError):
     """
     Raised when an infrastructure-related issue happened while running a test.
     """
-    pass
 
 
 from . import testcontrol  # noqa: F401, E402

atex/executor/duration.py

@@ -10,7 +10,7 @@ class Duration:
 
     def __init__(self, fmf_duration):
         """
-        'fmf_duration' is the string specified as 'duration' in FMF metadata.
+        - `fmf_duration` is the string specified as 'duration' in FMF metadata.
         """
         duration = self._fmf_to_seconds(fmf_duration)
         self.end = time.monotonic() + duration

atex/executor/executor.py

@@ -46,16 +46,18 @@ class Executor:
 
     def __init__(self, fmf_tests, connection, *, env=None, state_dir=None):
         """
-        'fmf_tests' is a class FMFTests instance with (discovered) tests.
+        - `fmf_tests` is a class FMFTests instance with (discovered) tests.
 
-        'connection' is a class Connection instance, already fully connected.
+        - `connection` is a class Connection instance, already fully connected.
 
-        'env' is a dict of extra environment variables to pass to the
-        plan prepare/finish scripts and to all tests.
+        - `env` is a dict of extra environment variables to pass to the
+          plan prepare/finish scripts and to all tests.
 
-        'state_dir' is a string or Path specifying path on the remote system for
-        storing additional data, such as tests, execution wrappers, temporary
-        plan-exported variables, etc. If left as None, a tmpdir is used.
+        - `state_dir` is a string or Path specifying path on the remote system
+          for storing additional data, such as tests, execution wrappers,
+          temporary plan-exported variables, etc.
+
+          If left as `None`, a tmpdir is used.
         """
         self.lock = threading.RLock()
         self.fmf_tests = fmf_tests
@@ -130,7 +132,7 @@ class Executor:
     def upload_tests(self):
         """
         Upload a directory of all tests, the location of which was provided to
-        __init__() inside 'fmf_tests', to the remote host.
+        `__init__()` inside `fmf_tests`, to the remote host.
         """
         self.conn.rsync(
             "-r", "--delete", "--exclude=.git/",
@@ -199,16 +201,19 @@ class Executor:
         """
         Run one test on the remote system.
 
-        'test_name' is a string with test name.
+        - `test_name` is a string with test name.
+
+        - `output_dir` is a destination dir (string or Path) for results reported
+          and files uploaded by the test.
+
+          Results are always stored in a line-JSON format in a file named
+          `results`, files are always uploaded to directory named `files`,
+          both inside `output_dir`.
 
-        'output_dir' is a destination dir (string or Path) for results reported
-        and files uploaded by the test. Results are always stored in a line-JSON
-        format in a file named 'results', files are always uploaded to directory
-        named 'files', both inside 'output_dir'.
-        The path for 'output_dir' must already exist and be an empty directory
-        (ie. typically a tmpdir).
+          The path for `output_dir` must already exist and be an empty directory
+          (ie. typically a tmpdir).
 
-        'env' is a dict of extra environment variables to pass to the test.
+        - `env` is a dict of extra environment variables to pass to the test.
 
         Returns an integer exit code of the test script.
         """
@@ -280,22 +285,26 @@ class Executor:
                             abort("cancel requested")
 
                     if state == self.State.STARTING_TEST:
-                        control_fd, pipe_w = os.pipe()
-                        os.set_blocking(control_fd, False)
-                        control.reassign(control_fd)
                         # reconnect/reboot count (for compatibility)
                         env_vars["TMT_REBOOT_COUNT"] = str(reconnects)
                         env_vars["TMT_TEST_RESTART_COUNT"] = str(reconnects)
-                        # run the test in the background, letting it log output directly to
-                        # an opened file (we don't handle it, cmd client sends it to kernel)
                         env_args = (f"{k}={v}" for k, v in env_vars.items())
-                        test_proc = self.conn.cmd(
-                            ("env", *env_args, f"{self.work_dir}/wrapper.sh"),
-                            stdout=pipe_w,
-                            stderr=reporter.testout_fobj.fileno(),
-                            func=util.subprocess_Popen,
-                        )
-                        os.close(pipe_w)
+                        try:
+                            # open a pipe for test control
+                            control_fd, pipe_w = os.pipe()
+                            os.set_blocking(control_fd, False)
+                            control.reassign(control_fd)
+                            # run the test in the background, letting it log output directly to
+                            # an opened file (we don't handle it, cmd client sends it to kernel)
+                            with reporter.open_testout() as testout_fd:
+                                test_proc = self.conn.cmd(
+                                    ("env", *env_args, f"{self.work_dir}/wrapper.sh"),
+                                    stdout=pipe_w,
+                                    stderr=testout_fd,
+                                    func=util.subprocess_Popen,
+                                )
+                        finally:
+                            os.close(pipe_w)
                         state = self.State.READING_CONTROL
 
                     elif state == self.State.READING_CONTROL:
@@ -304,7 +313,7 @@ class Executor:
                             abort(f"got exceptional condition on control_fd {control_fd}")
                         elif rlist:
                             control.process()
-                            if control.eof:
+                            if control.eof or control.disconnect_received:
                                 os.close(control_fd)
                                 control_fd = None
                                 state = self.State.WAITING_FOR_EXIT
@@ -320,11 +329,16 @@ class Executor:
                             else:
                                 # unexpected error happened (crash, disconnect, etc.)
                                 self.conn.disconnect()
-                                # if reconnect was requested, do so, otherwise abort
-                                if control.reconnect:
+                                # if there was a test control parser running
+                                if control.in_progress:
+                                    abort(
+                                        f"{str(control.in_progress)} was running while test "
+                                        f"wrapper unexpectedly exited with {code}",
+                                    )
+                                # if test control disconnect was intentional, try to reconnect
+                                if control.disconnect_received:
                                     state = self.State.RECONNECTING
-                                    if control.reconnect != "always":
-                                        control.reconnect = None
+                                    control.disconnect_received = False
                                 else:
                                     abort(
                                         f"test wrapper unexpectedly exited with {code} and "

atex/executor/reporter.py

@@ -1,5 +1,6 @@
 import os
 import json
+import contextlib
 from pathlib import Path
 
 from .. import util
@@ -17,32 +18,30 @@ class Reporter:
 
     def __init__(self, output_dir, results_file, files_dir):
         """
-        'output_dir' is a destination dir (string or Path) for results reported
-        and files uploaded.
+        - `output_dir` is a destination dir (string or Path) for results
+          reported and files uploaded.
 
-        'results_file' is a file name inside 'output_dir' the results will be
-        reported into.
+        - `results_file` is a file name inside `output_dir` the results
+          will be reported into.
 
-        'files_dir' is a dir name inside 'output_dir' any files will be
-        uploaded to.
+        - `files_dir` is a dir name inside `output_dir` any files will be
+          uploaded to.
         """
-        output_dir = Path(output_dir)
-        self.testout_file = output_dir / self.TESTOUT
-        self.results_file = output_dir / results_file
-        self.files_dir = output_dir / files_dir
-        self.output_dir = output_dir
+        self.output_dir = Path(output_dir)
+        self.results_file = self.output_dir / results_file
         self.results_fobj = None
-        self.testout_fobj = None
+        self.files_dir = self.output_dir / files_dir
+        self.testout_file = self.output_dir / self.TESTOUT
 
     def start(self):
-        if self.testout_file.exists():
-            raise FileExistsError(f"{self.testout_file} already exists")
-        self.testout_fobj = open(self.testout_file, "wb")
-
         if self.results_file.exists():
             raise FileExistsError(f"{self.results_file} already exists")
         self.results_fobj = open(self.results_file, "w", newline="\n")
 
+        if self.testout_file.exists():
+            raise FileExistsError(f"{self.testout_file} already exists")
+        self.testout_file.touch()
+
         if self.files_dir.exists():
             raise FileExistsError(f"{self.files_dir} already exists")
         self.files_dir.mkdir()
@@ -51,11 +50,7 @@ class Reporter:
         if self.results_fobj:
             self.results_fobj.close()
             self.results_fobj = None
-
-        if self.testout_fobj:
-            self.testout_fobj.close()
-            self.testout_fobj = None
-            Path(self.testout_file).unlink()
+        self.testout_file.unlink(missing_ok=True)
 
     def __enter__(self):
         try:
@@ -72,7 +67,7 @@ class Reporter:
         """
         Persistently record a test result.
 
-        'result_line' is a dict in the format specified by RESULTS.md.
+        - `result_line` is a dict in the format specified by RESULTS.md.
         """
         json.dump(result_line, self.results_fobj, indent=None)
         self.results_fobj.write("\n")
@@ -85,15 +80,32 @@ class Reporter:
         file_path.parent.mkdir(parents=True, exist_ok=True)
         return file_path
 
-    def open_fd(self, file_name, mode, result_name=None):
+    @contextlib.contextmanager
+    def open_file(self, file_name, mode, result_name=None):
         """
-        Open a file named 'file_name' in a directory relevant to 'result_name'.
-        Returns an opened file descriptor that can be closed with os.close().
+        Open a file named `file_name` in a directory relevant to `result_name`.
+        Yields an opened file descriptor (as integer) as a Context Manager.
 
-        If 'result_name' (typically a subtest) is not given, open the file
+        If `result_name` (typically a subtest) is not given, open the file
         for the test (name) itself.
         """
-        return os.open(self._dest_path(file_name, result_name), mode)
+        fd = os.open(self._dest_path(file_name, result_name), mode)
+        try:
+            yield fd
+        finally:
+            os.close(fd)
+
+    @contextlib.contextmanager
+    def open_testout(self):
+        """
+        Open a file named after self.TESTOUT inside self.output_dir.
+        Yields an opened file descriptor (as integer) as a Context Manager.
+        """
+        fd = os.open(self.testout_file, os.O_WRONLY | os.O_CREAT | os.O_APPEND)
+        try:
+            yield fd
+        finally:
+            os.close(fd)
 
     def link_testout(self, file_name, result_name=None):
         # TODO: docstring

atex/executor/scripts.py

@@ -34,12 +34,12 @@ def test_wrapper(*, test, tests_dir, test_exec):
     is considered as test output and any unintended environment changes
     will impact the test itself.
 
-    'test' is a class Test instance.
+    - `test` is a class Test instance.
 
-    'test_dir' is a remote directory (repository) of all the tests,
-    a.k.a. FMF metadata root.
+    - `test_dir` is a remote directory (repository) of all the tests,
+      a.k.a. FMF metadata root.
 
-    'test_exec' is a remote path to the actual test to run.
+    - `test_exec` is a remote path to the actual test to run.
     """
     out = "#!/bin/bash\n"
 
@@ -104,13 +104,13 @@ def test_setup(*, test, wrapper_exec, test_exec, test_yaml, **kwargs):
     scripts: a test script (contents of 'test' from FMF) and a wrapper script
     to run the test script.
 
-    'test' is a class Test instance.
+    - `test` is a class Test instance.
 
-    'wrapper_exec' is the remote path where the wrapper script should be put.
+    - `wrapper_exec` is the remote path where the wrapper script should be put.
 
-    'test_exec' is the remote path where the test script should be put.
+    - `test_exec` is the remote path where the test script should be put.
 
-    Any 'kwargs' are passed to test_wrapper().
+    Any `kwargs` are passed to `test_wrapper()`.
     """
     out = "#!/bin/bash\n"
 

atex/executor/testcontrol.py

@@ -1,8 +1,9 @@
 import os
-import collections
 import json
+import logging
+import collections
 
-from .. import util
+logger = logging.getLogger("atex.executor.testcontrol")
 
 
 class BufferFullError(Exception):
@@ -12,21 +13,22 @@ class BufferFullError(Exception):
 class NonblockLineReader:
     """
     Kind of like io.BufferedReader but capable of reading from non-blocking
-    sources (both O_NONBLOCK sockets and os.set_blocking(False) descriptors),
-    re-assembling full lines from (potentially) multiple read() calls.
+    sources (both `O_NONBLOCK` sockets and `os.set_blocking(False)`
+    descriptors), re-assembling full lines from (potentially) multiple
+    `read()` calls.
 
     It also takes a file descriptor (not a file-like object) and takes extra
     care to read one-byte-at-a-time to not read (and buffer) more data from the
     source descriptor, allowing it to be used for in-kernel move, such as via
-    os.sendfile() or os.splice().
+    `os.sendfile()` or `os.splice()`.
     """
 
     def __init__(self, src, maxlen=4096):
         """
-        'src' is an opened file descriptor (integer).
+        - `src` is an opened file descriptor (integer).
 
-        'maxlen' is a maximum potential line length, incl. the newline
-        character - if reached, a BufferFullError is raised.
+        - `maxlen` is a maximum potential line length, incl. the newline
+          character - if reached, a BufferFullError is raised.
         """
         self.src = src
         self.eof = False
@@ -35,7 +37,7 @@ class NonblockLineReader:
 
     def readline(self):
         r"""
-        Read a line and return it, without the '\n' terminating character,
+        Read a line and return it, without the `\n` terminating character,
         clearing the internal buffer upon return.
 
         Returns None if nothing could be read (BlockingIOError) or if EOF
@@ -77,7 +79,6 @@ class BadControlError(Exception):
     such as invalid syntax, unknown control word, or bad or unexpected data for
     any given control word.
     """
-    pass
 
 
 class BadReportJSONError(BadControlError):
@@ -86,7 +87,6 @@ class BadReportJSONError(BadControlError):
     the TEST_CONROL.md specification when passing JSON data to the 'result'
     control word.
     """
-    pass
 
 
 class TestControl:
@@ -97,12 +97,12 @@ class TestControl:
 
     def __init__(self, *, reporter, duration, control_fd=None):
         """
-        'control_fd' is a non-blocking file descriptor to be read.
+        - `control_fd` is a non-blocking file descriptor to be read.
 
-        'reporter' is an instance of class Reporter all the results
-        and uploaded files will be written to.
+        - `reporter` is an instance of class Reporter all the results
+          and uploaded files will be written to.
 
-        'duration' is a class Duration instance.
+        - `duration` is a class Duration instance.
         """
         self.reporter = reporter
         self.duration = duration
@@ -116,7 +116,7 @@ class TestControl:
         self.in_progress = None
         self.partial_results = collections.defaultdict(dict)
         self.exit_code = None
-        self.reconnect = None
+        self.disconnect_received = False
         self.nameless_result_seen = False
 
     def reassign(self, new_fd):
@@ -138,7 +138,7 @@ class TestControl:
         Read from the control file descriptor and potentially perform any
         appropriate action based on commands read from the test.
 
-        Returns True if there is more data expected, False otherwise
+        Returns `True` if there is more data expected, `False` otherwise
         (when the control file descriptor reached EOF).
         """
         # if a parser operation is in progress, continue calling it,
@@ -156,7 +156,7 @@ class TestControl:
         except BufferFullError as e:
             raise BadControlError(str(e)) from None
 
-        util.extradebug(f"control line: {line} // eof: {self.stream.eof}")
+        logger.debug(f"control line: {line} // eof: {self.stream.eof}")
 
         if self.stream.eof:
             self.eof = True
@@ -176,8 +176,10 @@ class TestControl:
             parser = self._parser_duration(arg)
         elif word == "exitcode":
             parser = self._parser_exitcode(arg)
-        elif word == "reconnect":
-            parser = self._parser_reconnect(arg)
+        elif word == "disconnect":
+            parser = self._parser_disconnect(arg)
+        elif word == "noop":
+            parser = self._parser_noop(arg)
         else:
             raise BadControlError(f"unknown control word: {word}")
 
@@ -191,8 +193,8 @@ class TestControl:
     @classmethod
     def _merge(cls, dst, src):
         """
-        Merge a 'src' dict into 'dst', using the rules described by
-        TEST_CONTROL.md for 'Partial results'.
+        Merge a `src` dict into `dst`, using the rules described by
+        TEST_CONTROL.md for "Partial results".
         """
         for key, value in src.items():
             # delete existing if new value is None (JSON null)
@@ -240,7 +242,7 @@ class TestControl:
                 yield
                 continue
             if chunk == b"":
-                raise BadControlError("EOF when reading data")
+                raise BadControlError(f"EOF when reading data, got so far: {json_data}")
             json_data += chunk
             json_length -= len(chunk)
             yield
@@ -267,8 +269,7 @@ class TestControl:
             except ValueError as e:
                 raise BadReportJSONError(f"file entry {file_name} length: {str(e)}") from None
 
-            fd = self.reporter.open_fd(file_name, os.O_WRONLY | os.O_CREAT, name)
-            try:
+            with self.reporter.open_file(file_name, os.O_WRONLY | os.O_CREAT, name) as fd:
                 # Linux can't do splice(2) on O_APPEND fds, so we open it above
                 # as O_WRONLY and just seek to the end, simulating append
                 os.lseek(fd, 0, os.SEEK_END)
@@ -290,8 +291,6 @@ class TestControl:
                         raise BadControlError("EOF when reading data")
                     file_length -= written
                     yield
-            finally:
-                os.close(fd)
 
         # either store partial result + return,
         # or load previous partial result and merge into it
@@ -326,6 +325,18 @@ class TestControl:
             except FileExistsError:
                 raise BadReportJSONError(f"file '{testout}' already exists") from None
 
+        # deduplicate file names
+        # - appending to files (multiple identical file 'name' in one result, or
+        #   using partial:true) can create large amounts of files:[] entries,
+        #   so simply add up all their lengths and specify each file 'name' once
+        if files := result.get("files"):
+            counter = collections.Counter()
+            for entry in files:
+                counter[entry["name"]] += entry["length"]
+            result["files"] = tuple(
+                {"name": name, "length": length} for name, length in counter.items()
+            )
+
         self.reporter.report(result)
 
     def _parser_duration(self, arg):
@@ -359,13 +370,14 @@ class TestControl:
         if False:
             yield
 
-    def _parser_reconnect(self, arg):
-        if not arg:
-            self.reconnect = "once"
-        elif arg == "always":
-            self.reconnect = "always"
-        else:
-            raise BadControlError(f"unknown reconnect arg: {arg}")
+    def _parser_disconnect(self, _):
+        self.disconnect_received = True
+        # pretend to be a generator
+        if False:
+            yield
+
+    @staticmethod
+    def _parser_noop(_):
         # pretend to be a generator
         if False:
             yield

atex/fmf.py

@@ -12,11 +12,15 @@ def listlike(data, key):
     defined as a dict or a list.
 
     This is needed because many fmf metadata keys can be used either as
+
         some_key: 123
+
     or as lists via YAML syntax
+
         some_key:
           - 123
           - 456
+
     and, for simplicity, we want to always deal with lists (iterables).
     """
     if value := data.get(key):
@@ -39,32 +43,34 @@ class FMFTests:
         context=None,
     ):
         """
-        'fmf_tree' is filesystem path somewhere inside fmf metadata tree,
-        or a root fmf.Tree instance.
+        - `fmf_tree` is filesystem path somewhere inside fmf metadata tree,
+          or a root fmf.Tree instance.
 
-        'plan_name' is fmf identifier (like /some/thing) of a tmt plan
-        to use for discovering tests. If None, a dummy (empty) plan is used.
+        - `plan_name` is fmf identifier (like `/some/thing`) of a tmt plan
+          to use for discovering tests. If None, a dummy (empty) plan is used.
 
-        'names', 'filters', 'conditions' and 'exclude' (all tuple/list)
-        are fmf tree filters (resolved by the fmf module), overriding any
-        existing tree filters in the plan's discover phase specifies, where:
+        - `names`, `filters`, `conditions` and `exclude` (all tuple/list)
+          are fmf tree filters (resolved by the fmf module), overriding any
+          existing tree filters in the plan's discover phase specifies, where:
 
-            'names' are test regexes like ["/some/test", "/another/test"]
+            - `names` are test regexes like `["/some/test", "/another/test"]`.
 
-            'filters' are fmf-style filter expressions, as documented on
-            https://fmf.readthedocs.io/en/stable/modules.html#fmf.filter
+            - `filters` are fmf-style filter expressions, as documented on
+              https://fmf.readthedocs.io/en/stable/modules.html#fmf.filter
 
-            'conditions' are python expressions whose namespace locals()
-            are set up to be a dictionary of the fmf tree. When any of the
-            expressions returns True, the tree is returned, ie.
-                ["environment['FOO'] == 'BAR'"]
-                ["'enabled' not in locals() or enabled"]
-            Note that KeyError is silently ignored and treated as False.
+            - `conditions` are python expressions whose namespace `locals()`
+              are set up to be a dictionary of the fmf tree. When any of the
+              expressions returns `True`, the tree is returned, ie.
 
-            'excludes' are test regexes to exclude, format same as 'names'
+                  ["environment['FOO'] == 'BAR'"]
+                  ["'enabled' not in locals() or enabled"]
 
-        'context' is a dict like {'distro': 'rhel-9.6'} used for additional
-        adjustment of the discovered fmf metadata.
+              Note that KeyError is silently ignored and treated as `False`.
+
+            - `excludes` are test regexes to exclude, format same as `names`.
+
+        - `context` is a dict like `{'distro': 'rhel-9.6'}` used for additional
+          adjustment of the discovered fmf metadata.
         """
         # list of packages to install, as extracted from plan
         self.prepare_pkgs = []
@@ -187,8 +193,8 @@ class FMFTests:
 
 def test_pkg_requires(data, key="require"):
     """
-    Yield RPM package names specified by test 'data' (fmf metadata dict)
-    in the metadata 'key' (require or recommend), ignoring any non-RPM-package
+    Yield RPM package names specified by test `data` (fmf metadata dict)
+    in the metadata `key` (require or recommend), ignoring any non-RPM-package
     requires/recommends.
     """
     for entry in listlike(data, key):
@@ -204,7 +210,7 @@ def test_pkg_requires(data, key="require"):
 def all_pkg_requires(fmf_tests, key="require"):
     """
     Yield RPM package names from the plan and all tests discovered by
-    a class FMFTests instance 'fmf_tests', ignoring any non-RPM-package
+    a class FMFTests instance `fmf_tests`, ignoring any non-RPM-package
     requires/recommends.
     """
     # use a set to avoid duplicates
@@ -213,25 +219,3 @@ def all_pkg_requires(fmf_tests, key="require"):
     for data in fmf_tests.tests.values():
         pkgs.update(test_pkg_requires(data, key))
     yield from pkgs
-
-
-# Some extra notes for fmf.prune() arguments:
-#
-# Set 'names' to filter by a list of fmf node names, ie.
-#     ['/some/test', '/another/test']
-#
-# Set 'filters' to filter by a list of fmf-style filter expressions, see
-#     https://fmf.readthedocs.io/en/stable/modules.html#fmf.filter
-#
-# Set 'conditions' to filter by a list of python expressions whose namespace
-# locals() are set up to be a dictionary of the tree. When any of the
-# expressions returns True, the tree is returned, ie.
-#     ['environment["FOO"] == "BAR"']
-#     ['"enabled" not in locals() or enabled']
-# Note that KeyError is silently ignored and treated as False.
-#
-# Set 'context' to a dictionary to post-process the tree metadata with
-# adjust expressions (that may be present in a tree) using the specified
-# context. Any other filters are applied afterwards to allow modification
-# of tree metadata by the adjust expressions. Ie.
-#     {'distro': 'rhel-9.6.0', 'arch': 'x86_64'}