gha-utils 4.14.2__py3-none-any.whl → 4.15.0__py3-none-any.whl

gha_utils/__init__.py

@@ -17,4 +17,4 @@
 
 from __future__ import annotations
 
-__version__ = "4.14.2"
+__version__ = "4.15.0"

gha_utils/changelog.py

@@ -18,15 +18,11 @@ from __future__ import annotations
 
 import logging
 import re
-import sys
 from functools import cached_property
 from pathlib import Path
 from textwrap import indent
 
-if sys.version_info >= (3, 11):
-    import tomllib
-else:
-    import tomli as tomllib  # type: ignore[import-not-found]
+import tomllib
 
 
 class Changelog:

gha_utils/cli.py

@@ -19,11 +19,12 @@ from __future__ import annotations
 import logging
 import os
 import sys
+from collections import Counter
 from datetime import datetime
 from pathlib import Path
 from typing import IO
 
-import click
+from boltons.iterutils import unique
 from click_extra import (
     Choice,
     Context,
@@ -35,12 +36,14 @@ from click_extra import (
     option,
     pass_context,
 )
+from click_extra.envvar import merge_envvar_ids
+from extra_platforms import ALL_IDS
 
 from . import __version__
 from .changelog import Changelog
 from .mailmap import Mailmap
 from .metadata import Dialects, Metadata
-from .test_plan import DEFAULT_TEST_PLAN, parse_test_plan
+from .test_plan import DEFAULT_TEST_PLAN, SkippedTest, parse_test_plan
 
 
 def is_stdout(filepath: Path) -> bool:
@@ -275,19 +278,38 @@ def mailmap_sync(ctx, source, create_if_missing, destination_mailmap):
 @gha_utils.command(short_help="Run a test plan from a file against a binary")
 @option(
     "--binary",
-    # XXX Wait for https://github.com/janluke/cloup/issues/185 to use the
-    # `file_path` type.
-    type=click.Path(exists=True, executable=True, resolve_path=True),
+    type=file_path(exists=True, executable=True, resolve_path=True),
     required=True,
     metavar="FILE_PATH",
     help="Path to the binary file to test.",
 )
 @option(
+    "-F",
+    "--plan-file",
+    # TODO: remove deprecated --plan option to avoid confusion.
     "--plan",
     type=file_path(exists=True, readable=True, resolve_path=True),
+    multiple=True,
     metavar="FILE_PATH",
-    help="Path to the test plan file in YAML. If not provided, a default test "
-    "plan will be executed.",
+    help="Path to a test plan file in YAML. This option can be repeated to run "
+    "multiple test plans in sequence. If not provided, a default test plan will be "
+    "executed.",
+)
+@option(
+    "-E",
+    "--plan-envvar",
+    multiple=True,
+    metavar="ENVVAR_NAME",
+    help="Name of an environment variable containing a test plan in YAML. This "
+    "option can be repeated to collect multiple test plans.",
+)
+@option(
+    "-s",
+    "--skip-platform",
+    type=Choice(sorted(ALL_IDS), case_sensitive=False),
+    multiple=True,
+    help="Skip tests for the specified platforms. This option can be repeated to "
+    "skip multiple platforms.",
 )
 @option(
     "-t",
@@ -300,17 +322,54 @@ def mailmap_sync(ctx, source, create_if_missing, destination_mailmap):
     help="Set the default timeout for each CLI call, if not specified in the "
     "test plan.",
 )
-def test_plan(binary: Path, plan: Path | None, timeout: float | None) -> None:
+def test_plan(
+    binary: Path,
+    plan_file: tuple[Path, ...] | None,
+    plan_envvar: tuple[str, ...] | None,
+    skip_platform: tuple[str, ...] | None,
+    timeout: float | None,
+) -> None:
     # Load test plan from workflow input, or use a default one.
-    if plan:
-        logging.info(f"Read test plan from {plan}")
-        test_plan = parse_test_plan(plan)
+    test_list = []
+    if plan_file or plan_envvar:
+        for file in unique(plan_file):
+            logging.info(f"Get test plan from {file} file")
+            tests = list(parse_test_plan(file.read_text(encoding="UTF-8")))
+            logging.info(f"{len(tests)} test cases found.")
+            test_list.extend(tests)
+        for envvar_id in merge_envvar_ids(plan_envvar):
+            logging.info(f"Get test plan from {envvar_id!r} environment variable")
+            tests = list(parse_test_plan(os.getenv(envvar_id)))
+            logging.info(f"{len(tests)} test cases found.")
+            test_list.extend(tests)
+
     else:
-        logging.warning("No test plan provided: use default test plan.")
-        test_plan = DEFAULT_TEST_PLAN  # type: ignore[assignment]
-    logging.debug(f"Test plan: {test_plan}")
+        logging.warning(
+            "No test plan provided through --plan-file/-F or --plan-envvar/-E options:"
+            " use default test plan."
+        )
+        test_list = DEFAULT_TEST_PLAN
+    logging.debug(f"Test plan: {test_list}")
+
+    stats = Counter(total=len(test_list), skipped=0, failed=0)
 
-    for index, test_case in enumerate(test_plan):
+    for index, test_case in enumerate(test_list):
         logging.info(f"Run test #{index + 1}")
-        logging.debug(f"Test case parameters: {test_case}")
-        test_case.check_cli_test(binary, default_timeout=timeout)
+        try:
+            logging.debug(f"Test case parameters: {test_case}")
+            test_case.run_cli_test(
+                binary, additional_skip_platforms=skip_platform, default_timeout=timeout
+            )
+        except SkippedTest as ex:
+            stats["skipped"] += 1
+            logging.warning(f"Test skipped: {ex}")
+        except Exception as ex:
+            stats["failed"] += 1
+            logging.error(f"Test failed: {ex}")
+
+    logging.info(
+        "Test plan results - "
+        + ", ".join((f"{k.title()}: {v}" for k, v in stats.items()))
+    )
+    if stats["failed"]:
+        sys.exit(1)

gha_utils/metadata.py

@@ -49,7 +49,7 @@ release_commits_matrix={'commit': ['6f27db47612aaee06fdf08744b09a9f5f6c2'],
 nuitka_matrix={'entry_point': ['mpm'],
                'commit': ['346ce664f055fbd042a25ee0b7e96702e95',
                           '6f27db47612aaee06fdf08744b09a9f5f6c2'],
-                'os': ['ubuntu-24.04', 'ubuntu-24.04-arm', 'macos-15', 'macos-13', 'windows-2022'],
+                'os': ['ubuntu-24.04', 'ubuntu-24.04-arm', 'macos-15', 'macos-13', 'windows-2025'],
                 'include': [{'entry_point': 'mpm',
                              'cli_id': 'mpm',
                              'module_id': 'meta_package_manager.__main__',
@@ -77,7 +77,7 @@ nuitka_matrix={'entry_point': ['mpm'],
                              'platform_id': 'macos',
                              'arch': 'x64',
                              'extension': 'bin'},
-                            {'os': 'windows-2022',
+                            {'os': 'windows-2025',
                              'platform_id': 'windows',
                              'arch': 'x64',
                              'extension': 'exe'},
@@ -123,12 +123,12 @@ nuitka_matrix={'entry_point': ['mpm'],
                              'bin_name': 'mpm-macos-x64-build-6f27db4.bin'},
                             {'entry_point': 'mpm',
                              'commit': '346ce664f055fbd042a25ee0b7e96702e95',
-                             'os': 'windows-2022',
+                             'os': 'windows-2025',
                              'arch': 'x64',
                              'bin_name': 'mpm-windows-x64-build-346ce66.exe'},
                             {'entry_point': 'mpm',
                              'commit': '6f27db47612aaee06fdf08744b09a9f5f6c2',
-                             'os': 'windows-2022',
+                             'os': 'windows-2025',
                              'arch': 'x64',
                              'bin_name': 'mpm-windows-x64-build-6f27db4.exe'}]}
 ```
@@ -147,22 +147,15 @@ import json
 import logging
 import os
 import re
-import sys
 from collections.abc import Iterable
+from enum import StrEnum
 from functools import cached_property
 from pathlib import Path
 from random import randint
 from re import escape
 from typing import Any, Final, Iterator, cast
 
-if sys.version_info >= (3, 11):
-    from enum import StrEnum
-
-    import tomllib
-else:
-    import tomli as tomllib  # type: ignore[import-not-found]
-    from backports.strenum import StrEnum  # type: ignore[import-not-found]
-
+import tomllib
 from bumpversion.config import get_configuration  # type: ignore[import-untyped]
 from bumpversion.config.files import find_config_file  # type: ignore[import-untyped]
 from bumpversion.show import resolve_name  # type: ignore[import-untyped]
@@ -457,7 +450,7 @@ class Metadata:
         return matrix
 
     @cached_property
-    def event_type(self) -> WorkflowEvent | None:  # type: ignore[valid-type]
+    def event_type(self) -> WorkflowEvent | None:
         """Returns the type of event that triggered the workflow run.
 
         .. caution::
@@ -481,8 +474,8 @@ class Metadata:
             return None
 
         if bool(os.environ.get("GITHUB_BASE_REF")):
-            return WorkflowEvent.pull_request  # type: ignore[no-any-return]
-        return WorkflowEvent.push  # type: ignore[no-any-return]
+            return WorkflowEvent.pull_request
+        return WorkflowEvent.push
 
     @cached_property
     def commit_range(self) -> tuple[str, str] | None:
@@ -515,7 +508,7 @@ class Metadata:
         if not self.github_context or not self.event_type:
             return None
         # Pull request event.
-        if self.event_type in (  # type: ignore[unreachable]
+        if self.event_type in (
             WorkflowEvent.pull_request,
             WorkflowEvent.pull_request_target,
         ):
@@ -880,7 +873,7 @@ class Metadata:
                     "ubuntu-24.04-arm",
                     "macos-15",
                     "macos-13",
-                    "windows-2022",
+                    "windows-2025",
                 ],
                 "include": [
                     {
@@ -925,7 +918,7 @@ class Metadata:
                         "extension": "bin",
                     },
                     {
-                        "os": "windows-2022",
+                        "os": "windows-2025",
                         "platform_id": "windows",
                         "arch": "x64",
                         "extension": "exe",
@@ -989,14 +982,14 @@ class Metadata:
                     {
                         "entry_point": "mpm",
                         "commit": "346ce664f055fbd042a25ee0b7e96702e95",
-                        "os": "windows-2022",
+                        "os": "windows-2025",
                         "arch": "x64",
                         "bin_name": "mpm-windows-x64-build-346ce66.exe",
                     },
                     {
                         "entry_point": "mpm",
                         "commit": "6f27db47612aaee06fdf08744b09a9f5f6c2",
-                        "os": "windows-2022",
+                        "os": "windows-2025",
                         "arch": "x64",
                         "bin_name": "mpm-windows-x64-build-6f27db4.exe",
                     },
@@ -1021,7 +1014,7 @@ class Metadata:
                 "ubuntu-24.04-arm",  # arm64
                 "macos-15",  # arm64
                 "macos-13",  # x64
-                "windows-2022",  # x64
+                "windows-2025",  # x64
             ),
         )
 
@@ -1086,7 +1079,7 @@ class Metadata:
                 "extension": "bin",
             },
             {
-                "os": "windows-2022",
+                "os": "windows-2025",
                 "platform_id": "windows",
                 "arch": "x64",
                 "extension": "exe",
@@ -1180,10 +1173,7 @@ class Metadata:
 
         return cast(str, value)
 
-    def dump(
-        self,
-        dialect: Dialects = Dialects.github,  # type: ignore[valid-type]
-    ) -> str:
+    def dump(self, dialect: Dialects = Dialects.github) -> str:
         """Returns all metadata in the specified format.
 
         Defaults to GitHub dialect.

gha_utils/test_plan.py

@@ -28,14 +28,23 @@ from typing import Generator, Sequence
 import yaml
 from boltons.iterutils import flatten
 from boltons.strutils import strip_ansi
-from click_extra.testing import args_cleanup, print_cli_run
+from click_extra.testing import args_cleanup, render_cli_run
+from extra_platforms import Group, _TNestedReferences, current_os
+
+
+class SkippedTest(Exception):
+    """Raised when a test case should be skipped."""
+
+    pass
 
 
 @dataclass(order=True)
-class TestCase:
+class CLITestCase:
     cli_parameters: tuple[str, ...] | str = field(default_factory=tuple)
     """Parameters, arguments and options to pass to the CLI."""
 
+    skip_platforms: _TNestedReferences = field(default_factory=tuple)
+    only_platforms: _TNestedReferences = field(default_factory=tuple)
     timeout: float | str | None = None
     exit_code: int | str | None = None
     strip_ansi: bool = False
@@ -101,6 +110,10 @@ class TestCase:
                     # Ignore blank value.
                     field_data = tuple(i for i in field_data if i.strip())
 
+            # Normalize any mishmash of platform and group IDs into a set of platforms.
+            if field_id.endswith("_platforms") and field_data:
+                field_data = frozenset(Group._extract_platforms(field_data))
+
             # Validates fields containing one or more regexes.
             if "_regex_" in field_id and field_data:
                 # Compile all regexes.
@@ -124,16 +137,30 @@ class TestCase:
 
             setattr(self, field_id, field_data)
 
-    def check_cli_test(self, binary: str | Path, default_timeout: float | None):
+    def run_cli_test(
+        self,
+        binary: str | Path,
+        additional_skip_platforms: _TNestedReferences | None,
+        default_timeout: float | None,
+    ):
         """Run a CLI command and check its output against the test case.
 
         ..todo::
             Add support for environment variables.
 
         ..todo::
-            Add support for proper mixed stdout/stderr stream as a single,
+            Add support for proper mixed <stdout>/<stderr> stream as a single,
             intertwined output.
         """
+        if self.only_platforms:
+            if current_os() not in self.only_platforms:  # type: ignore[operator]
+                raise SkippedTest(f"Test case only runs on platform: {current_os()}")
+
+        if current_os() in Group._extract_platforms(
+            self.skip_platforms, additional_skip_platforms
+        ):
+            raise SkippedTest(f"Skipping test case on platform: {current_os()}")
+
         if self.timeout is None and default_timeout is not None:
             logging.info(f"Set default test case timeout to {default_timeout} seconds")
             self.timeout = default_timeout
@@ -176,7 +203,8 @@ class TestCase:
                 f"CLI timed out after {self.timeout} seconds: {' '.join(clean_args)}"
             )
 
-        print_cli_run(clean_args, result)
+        for line in render_cli_run(clean_args, result).splitlines():
+            logging.info(line)
 
         for field_id, field_data in asdict(self).items():
             if field_id == "exit_code":
@@ -211,55 +239,50 @@ class TestCase:
                 name = "<stderr>"
 
             if self.strip_ansi:
-                logging.info(f"Strip ANSI escape sequences from CLI's {name}")
+                logging.info(f"Strip ANSI sequences from {name}")
                 output = strip_ansi(output)
 
             if field_id.endswith("_contains"):
                 for sub_string in field_data:
-                    logging.info(f"Check if CLI's {name} contains: {sub_string!r}")
+                    logging.info(f"Check if {name} contains {sub_string!r}")
                     if sub_string not in output:
-                        raise AssertionError(
-                            f"CLI's {name} does not contain {sub_string!r}"
-                        )
+                        raise AssertionError(f"{name} does not contain {sub_string!r}")
 
             elif field_id.endswith("_regex_matches"):
                 for regex in field_data:
-                    logging.info(f"Check if CLI's {name} matches: {sub_string!r}")
+                    logging.info(f"Check if {name} matches {sub_string!r}")
                     if not regex.search(output):
-                        raise AssertionError(
-                            f"CLI's {name} does not match regex {regex}"
-                        )
+                        raise AssertionError(f"{name} does not match regex {regex}")
 
             elif field_id.endswith("_regex_fullmatch"):
                 regex = field_data
                 if not regex.fullmatch(output):
-                    raise AssertionError(
-                        f"CLI's {name} does not fully match regex {regex}"
-                    )
-
-        logging.info("All tests passed for CLI.")
+                    raise AssertionError(f"{name} does not fully match regex {regex}")
 
 
-DEFAULT_TEST_PLAN = (
+DEFAULT_TEST_PLAN: list[CLITestCase] = [
     # Output the version of the CLI.
-    TestCase(cli_parameters="--version"),
+    CLITestCase(cli_parameters="--version"),
     # Test combination of version and verbosity.
-    TestCase(cli_parameters=("--verbosity", "DEBUG", "--version")),
+    CLITestCase(cli_parameters=("--verbosity", "DEBUG", "--version")),
     # Test help output.
-    TestCase(cli_parameters="--help"),
-)
+    CLITestCase(cli_parameters="--help"),
+]
+
 
+def parse_test_plan(plan_string: str | None) -> Generator[CLITestCase, None, None]:
+    if not plan_string:
+        raise ValueError("Empty test plan")
 
-def parse_test_plan(plan_path: Path) -> Generator[TestCase, None, None]:
-    plan = yaml.full_load(plan_path.read_text(encoding="UTF-8"))
+    plan = yaml.full_load(plan_string)
 
     # Validates test plan structure.
     if not plan:
-        raise ValueError(f"Empty test plan file {plan_path}")
+        raise ValueError("Empty test plan")
     if not isinstance(plan, list):
         raise ValueError(f"Test plan is not a list: {plan}")
 
-    directives = frozenset(TestCase.__dataclass_fields__.keys())
+    directives = frozenset(CLITestCase.__dataclass_fields__.keys())
 
     for index, test_case in enumerate(plan):
         # Validates test case structure.
@@ -271,4 +294,4 @@ def parse_test_plan(plan_path: Path) -> Generator[TestCase, None, None]:
                 f"{set(test_case) - directives}"
             )
 
-        yield TestCase(**test_case)
+        yield CLITestCase(**test_case)

{gha_utils-4.14.2.dist-info → gha_utils-4.15.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: gha-utils
-Version: 4.14.2
+Version: 4.15.0
 Summary: ⚙️ CLI helpers for GitHub Actions + reuseable workflows
 Author-email: Kevin Deldycke <kevin@deldycke.com>
 Project-URL: Homepage, https://github.com/kdeldycke/workflows
@@ -19,7 +19,6 @@ Classifier: Operating System :: MacOS :: MacOS X
 Classifier: Operating System :: Microsoft :: Windows
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
@@ -43,17 +42,16 @@ Classifier: Topic :: Text Processing :: Markup :: HTML
 Classifier: Topic :: Text Processing :: Markup :: Markdown
 Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
-Requires-Dist: backports.strenum~=1.3.1; python_version < "3.11"
 Requires-Dist: boltons>=24.0.0
-Requires-Dist: bump-my-version>=0.21.0
-Requires-Dist: click-extra~=4.14.1
+Requires-Dist: bump-my-version>=0.32.2
+Requires-Dist: click-extra~=4.15.0
+Requires-Dist: extra-platforms~=3.1.0
 Requires-Dist: packaging~=24.1
 Requires-Dist: PyDriller~=2.6
 Requires-Dist: pyproject-metadata~=0.9.0
 Requires-Dist: pyyaml~=6.0.0
-Requires-Dist: tomli~=2.0.1; python_version < "3.11"
 Requires-Dist: wcmatch>=8.5
 Provides-Extra: test
 Requires-Dist: coverage[toml]~=7.6.0; extra == "test"
@@ -137,7 +135,7 @@ $ uvx gha-utils --version
 gha-utils, version 4.9.0
 ```
 
-That's the best way to get started with `gha-utils`, and experiment with its features.
+That's the best way to get started with `gha-utils` and experiment with it.
 
 ### Executables
 

gha_utils-4.15.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+gha_utils/__init__.py,sha256=H4VVQ1RRW-KQELnav8RAL_mjRUNRgbZq3kGBdL-8-b8,866
+gha_utils/__main__.py,sha256=Dck9BjpLXmIRS83k0mghAMcYVYiMiFLltQdfRuMSP_Q,1703
+gha_utils/changelog.py,sha256=JR7iQrWjLoIOpVNe6iXQSyEii82_hM_zrYpR7QO_Uxo,5777
+gha_utils/cli.py,sha256=58uww5uCnKN6JGDZJ0Gm_ZG-VCuzHopKTXIxAcp7w9M,12936
+gha_utils/mailmap.py,sha256=naUqJYJnE3fLTjju1nd6WMm7ODiSaI2SHuJxRtmaFWs,6269
+gha_utils/matrix.py,sha256=_afJD0K-xZLNxwykVnUhD0Gj9cdO0Z43g3VHa-q_tkI,11941
+gha_utils/metadata.py,sha256=AbiEdWjcJfUaVwlhV31J-HXJldZgFB0OKS2fHJ60FXU,48282
+gha_utils/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gha_utils/test_plan.py,sha256=iuSfsJ9XoqsIUbqR0HrkooUvK17TFBtlx8HyCAtMVWM,12841
+gha_utils-4.15.0.dist-info/METADATA,sha256=K8Fjiy-evM6R223OvGk5E9jh9X8rBdarb_g-WJadJXo,20372
+gha_utils-4.15.0.dist-info/WHEEL,sha256=jB7zZ3N9hIM9adW7qlTAyycLYW9npaWKLRzaoVcLKcM,91
+gha_utils-4.15.0.dist-info/entry_points.txt,sha256=8bJOwQYf9ZqsLhBR6gUCzvwLNI9f8tiiBrJ3AR0EK4o,54
+gha_utils-4.15.0.dist-info/top_level.txt,sha256=C94Blb61YkkyPBwCdM3J_JPDjWH0lnKa5nGZeZ5M6yE,10
+gha_utils-4.15.0.dist-info/RECORD,,

{gha_utils-4.14.2.dist-info → gha_utils-4.15.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.8.0)
+Generator: setuptools (75.8.2)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

gha_utils-4.14.2.dist-info/RECORD

@@ -1,14 +0,0 @@
-gha_utils/__init__.py,sha256=dR8lNlVY_u847eZ0CTxmll40WHAkfXzWXN26hheu824,866
-gha_utils/__main__.py,sha256=Dck9BjpLXmIRS83k0mghAMcYVYiMiFLltQdfRuMSP_Q,1703
-gha_utils/changelog.py,sha256=oahY88A9FRV14f1JSFKIiYrN_TS7Jo3QlljXqJbeuaE,5892
-gha_utils/cli.py,sha256=Gq2pGpIOmvXtsexmg6nwN2ZuZ1lpHrJ5A43CeuDjK68,10985
-gha_utils/mailmap.py,sha256=naUqJYJnE3fLTjju1nd6WMm7ODiSaI2SHuJxRtmaFWs,6269
-gha_utils/matrix.py,sha256=_afJD0K-xZLNxwykVnUhD0Gj9cdO0Z43g3VHa-q_tkI,11941
-gha_utils/metadata.py,sha256=Oumkmo4-O549hxlw8zaTWIPkITpUxUjpulj_MXn6fjA,48649
-gha_utils/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-gha_utils/test_plan.py,sha256=B6EiiGWVTrNS7jSIO9EE0kebccx10Fn0ZPapJTOOyGA,11928
-gha_utils-4.14.2.dist-info/METADATA,sha256=uPoJ9lj1TvWEt1Izsipp-4R6bsQ-gwHjnqwILdpL0fQ,20514
-gha_utils-4.14.2.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
-gha_utils-4.14.2.dist-info/entry_points.txt,sha256=8bJOwQYf9ZqsLhBR6gUCzvwLNI9f8tiiBrJ3AR0EK4o,54
-gha_utils-4.14.2.dist-info/top_level.txt,sha256=C94Blb61YkkyPBwCdM3J_JPDjWH0lnKa5nGZeZ5M6yE,10
-gha_utils-4.14.2.dist-info/RECORD,,