squash: add docstrings, address linters

tmt/base.py

@@ -3555,6 +3555,13 @@ def plan_queue(self) -> Sequence[Plan]:
         return self.plans[:]
 
     def swap_plans(self, plan: Plan, *others: Plan) -> None:
+        """
+        Replace given plan with one or more plans.
+
+        :param plan: a plan to remove.
+        :param others: plans to put into the queue instead of ``plans``.
+        """
+
         plans = cast(list[Plan], self.plans)
         plan_queue = cast(list[Plan], self.plan_queue)
 

tmt/plugins/plan_shapers/__init__.py

@@ -17,57 +17,51 @@
 
 
 def provides_plan_shaper(
-        package_manager: str) -> Callable[[PlanShaperClass], PlanShaperClass]:
+        shaper: str) -> Callable[[PlanShaperClass], PlanShaperClass]:
     """
-    A decorator for registering package managers.
+    A decorator for registering plan shaper plugins.
 
-    Decorate a package manager plugin class to register a package manager.
+    Decorate a plan shaper plugin class to register a plan shaper.
     """
 
-    def _provides_plan_shaper(package_manager_cls: PlanShaperClass) -> PlanShaperClass:
+    def _provides_plan_shaper(plan_shaper_cls: PlanShaperClass) -> PlanShaperClass:
         _PLAN_SHAPER_PLUGIN_REGISTRY.register_plugin(
-            plugin_id=package_manager,
-            plugin=package_manager_cls,
+            plugin_id=shaper,
+            plugin=plan_shaper_cls,
             logger=tmt.log.Logger.get_bootstrap_logger())
 
-        return package_manager_cls
+        return plan_shaper_cls
 
     return _provides_plan_shaper
 
 
-def find_package_manager(name: str) -> 'PlanShaperClass':
-    """
-    Find a plan shaper by its name.
-
-    :raises GeneralError: when the plugin does not exist.
-    """
-
-    plugin = _PLAN_SHAPER_PLUGIN_REGISTRY.get_plugin(name)
-
-    if plugin is None:
-        raise tmt.utils.GeneralError(
-            f"Package manager '{name}' was not found in package manager registry.")
-
-    return plugin
-
-
 class PlanShaper(tmt.utils.Common):
-    """ A base class for package manager plugins """
+    """ A base class for plan shaper plugins """
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         super().__init__(*args, **kwargs)
 
     @classmethod
     def run_options(cls) -> list['ClickOptionDecoratorType']:
+        """ Return additional options for ``tmt run`` """
+
         raise NotImplementedError
 
     @classmethod
     def check(cls, plan: 'Plan', tests: list[tuple[str, 'Test']]) -> bool:
+        """ Check whether this shaper should be applied to the given plan """
+
         raise NotImplementedError
 
     @classmethod
     def apply(
             cls,
             plan: 'Plan',
             tests: list[tuple[str, 'Test']]) -> Iterator['Plan']:
+        """
+        Apply the shaper to a given plan and a set of tests.
+
+        :returns: a sequence of plans replacing the original plan.
+        """
+
         raise NotImplementedError

tmt/steps/discover/__init__.py

@@ -421,22 +421,23 @@ def tests(
             *,
             phase_name: Optional[str] = None,
             enabled: Optional[bool] = None) -> list[tuple[str, 'tmt.Test']]:
-        tests = self._failed_tests if self._failed_tests else self._tests
+        suitable_tests = self._failed_tests if self._failed_tests else self._tests
+        suitable_phases = [phase_name] if phase_name is not None else list(self._tests.keys())
+
+        def _iter_tests() -> Iterator[tuple[str, 'tmt.Test']]:
+            # PLR1704: this redefinition of `phase_name` is acceptable, the original
+            # value is not longer needed as it has been turned into `suitable_phases`.
+            for phase_name, phase_tests in suitable_tests.items():  # noqa: PLR1704
+                if phase_name not in suitable_phases:
+                    continue
 
-        def _iter_all_tests() -> Iterator[tuple[str, 'tmt.Test']]:
-            for phase_name, phase_tests in tests.items():
                 for test in phase_tests:
                     yield phase_name, test
 
-        def _iter_phase_tests() -> Iterator[tuple[str, 'tmt.Test']]:
-            assert phase_name is not None
-
-            for test in self._tests[phase_name]:
-                yield phase_name, test
-
-        iterator = _iter_all_tests if phase_name is None else _iter_phase_tests
-
         if enabled is None:
-            return list(iterator())
+            return list(_iter_tests())
 
-        return [(phase_name, test) for phase_name, test in iterator() if test.enabled is enabled]
+        return [
+            (phase_name, test)
+            for phase_name, test in _iter_tests()
+            if test.enabled is enabled]