gha-utils 4.21.0__py3-none-any.whl → 4.23.0__py3-none-any.whl

gha_utils/__init__.py

@@ -17,4 +17,4 @@
 
 from __future__ import annotations
 
-__version__ = "4.21.0"
+__version__ = "4.23.0"

gha_utils/cli.py

@@ -23,7 +23,6 @@ import sys
 from collections import Counter
 from datetime import datetime
 from pathlib import Path
-from typing import IO
 
 from boltons.iterutils import unique
 from click_extra import (
@@ -47,6 +46,10 @@ from .mailmap import Mailmap
 from .metadata import NUITKA_BUILD_TARGETS, Dialects, Metadata
 from .test_plan import DEFAULT_TEST_PLAN, SkippedTest, parse_test_plan
 
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import IO
+
 
 def is_stdout(filepath: Path) -> bool:
     """Check if a file path is set to stdout.
@@ -303,11 +306,11 @@ 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(
+    "--command",
     "--binary",
-    type=file_path(exists=True, executable=True, resolve_path=True),
     required=True,
-    metavar="FILE_PATH",
-    help="Path to the binary file to test.",
+    metavar="COMMAND",
+    help="Path to the binary file to test, or a command line to be executed.",
 )
 @option(
     "-F",
@@ -375,7 +378,7 @@ def mailmap_sync(ctx, source, create_if_missing, destination_mailmap):
     help="Print per-manager package statistics.",
 )
 def test_plan(
-    binary: Path,
+    command: str,
     plan_file: tuple[Path, ...] | None,
     plan_envvar: tuple[str, ...] | None,
     select_test: tuple[int, ...] | None,
@@ -422,7 +425,9 @@ def test_plan(
         try:
             logging.debug(f"Test case parameters: {test_case}")
             test_case.run_cli_test(
-                binary, additional_skip_platforms=skip_platform, default_timeout=timeout
+                command,
+                additional_skip_platforms=skip_platform,
+                default_timeout=timeout,
             )
         except SkippedTest as ex:
             counter["skipped"] += 1
@@ -430,8 +435,8 @@ def test_plan(
         except Exception as ex:
             counter["failed"] += 1
             logging.error(f"Test {test_name} failed: {ex}")
-            if show_trace_on_error:
-                echo(test_case.execution_trace or "No execution trace available.")
+            if show_trace_on_error and test_case.execution_trace:
+                echo(test_case.execution_trace)
             if exit_on_error:
                 logging.debug("Don't continue testing, a failed test was found.")
                 sys.exit(1)

gha_utils/matrix.py

@@ -19,11 +19,15 @@ from __future__ import annotations
 import itertools
 import json
 import logging
-from typing import Iterable, Iterator
 
 from boltons.dictutils import FrozenDict
 from boltons.iterutils import unique
 
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Iterator
+
+
 RESERVED_MATRIX_KEYWORDS = ["include", "exclude"]
 
 

gha_utils/metadata.py

@@ -31,6 +31,7 @@ yaml_files="config.yaml" ".github/workflows/lint.yaml" ".github/workflows/test.y
 workflow_files=".github/workflows/lint.yaml" ".github/workflows/test.yaml"
 doc_files="changelog.md" "readme.md" "docs/license.md"
 markdown_files="changelog.md" "readme.md" "docs/license.md"
+image_files=
 zsh_files=
 is_python_project=true
 package_name=click-extra
@@ -285,12 +286,12 @@ from operator import itemgetter
 from pathlib import Path
 from random import randint
 from re import escape
-from typing import Any, Final, cast
 
 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]
 from extra_platforms import is_github_ci
+from gitdb.exc import BadName  # type: ignore[import-untyped]
 from packaging.specifiers import SpecifierSet
 from packaging.version import Version
 from py_walk import get_parser_from_file
@@ -310,6 +311,11 @@ from wcmatch.glob import (
 
 from .matrix import Matrix
 
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Any, Final
+
+
 SHORT_SHA_LENGTH = 7
 """Default SHA length hard-coded to ``7``.
 
@@ -559,6 +565,59 @@ class Metadata:
         logging.debug(f"Number of stashes in repository: {count}")
         return count
 
+    def git_deepen(
+        self, commit_hash: str, max_attempts: int = 10, deepen_increment: int = 50
+    ) -> bool:
+        """Deepen a shallow clone until the provided ``commit_hash`` is found.
+
+        Progressively fetches more commits from the current repository until the
+        specified commit is found or max attempts is reached.
+
+        Returns ``True`` if the commit was found, ``False`` otherwise.
+        """
+        for attempt in range(max_attempts):
+            try:
+                _ = self.git.get_commit(commit_hash)
+                if attempt > 0:
+                    logging.info(
+                        f"Found commit {commit_hash} after {attempt} deepen "
+                        "operation(s)."
+                    )
+                return True
+            except (ValueError, BadName) as ex:
+                logging.debug(f"Commit {commit_hash} not found: {ex}")
+
+                current_depth = self.git.total_commits()
+
+                if attempt == max_attempts - 1:
+                    # We've exhausted all attempts
+                    logging.error(
+                        f"Cannot find commit {commit_hash} in repository after "
+                        f"{max_attempts} deepen attempts. "
+                        f"Final depth is {current_depth} commits."
+                    )
+                    return False
+
+                logging.info(
+                    f"Commit {commit_hash} not found at depth {current_depth}."
+                )
+                logging.info(
+                    f"Deepening by {deepen_increment} commits (attempt "
+                    f"{attempt + 1}/{max_attempts})..."
+                )
+
+                try:
+                    self.git.repo.git.fetch(f"--deepen={deepen_increment}")
+                    new_depth = self.git.total_commits()
+                    logging.debug(
+                        f"Repository deepened successfully. New depth: {new_depth}"
+                    )
+                except Exception as ex:
+                    logging.error(f"Failed to deepen repository: {ex}")
+                    return False
+
+        return False
+
     def commit_matrix(self, commits: Iterable[Commit] | None) -> Matrix | None:
         """Pre-compute a matrix of commits.
 
@@ -719,7 +778,10 @@ class Metadata:
     def event_sender_type(self) -> str | None:
         """Returns the type of the user that triggered the workflow run."""
         sender_type = self.github_context.get("event", {}).get("sender", {}).get("type")
-        return cast(str | None, sender_type)
+        if not sender_type:
+            return None
+        assert isinstance(sender_type, str)
+        return sender_type
 
     @cached_property
     def is_bot(self) -> bool:
@@ -736,7 +798,7 @@ class Metadata:
         return False
 
     @cached_property
-    def commit_range(self) -> tuple[str, str] | None:
+    def commit_range(self) -> tuple[str | None, str] | None:
         """Range of commits bundled within the triggering event.
 
         A workflow run is triggered by a singular event, which might encapsulate one or
@@ -777,13 +839,18 @@ class Metadata:
         ):
             base_ref = os.environ["GITHUB_BASE_REF"]
             assert base_ref
-            start = f"origin/{base_ref}"
+            assert (
+                self.github_context["event"]["pull_request"]["base"]["ref"] == base_ref
+            )
+            full_base_ref = f"origin/{base_ref}"
+            base_ref_sha = self.github_context["event"]["pull_request"]["base"]["sha"]
+            start = base_ref_sha
             # We need to checkout the HEAD commit instead of the artificial merge
             # commit introduced by the pull request.
             end = self.github_context["event"]["pull_request"]["head"]["sha"]
         # Push event.
         else:
-            start = self.github_context["event"]["before"]
+            start = self.github_context["event"].get("before")
             end = os.environ["GITHUB_SHA"]
             assert end
         logging.debug(f"Commit range: {start} -> {end}")
@@ -811,19 +878,20 @@ class Metadata:
         # inclusive), we still need to make sure it exists: PyDriller stills needs to
         # find it to be able to traverse the commit history.
         for commit_id in (start, end):
-            try:
-                _ = self.git.get_commit(commit_id)
-            except ValueError:
-                logging.error(
-                    f"Cannot find commit {commit_id} in repository. "
-                    "Repository was probably not checked out with enough depth. "
-                    f"Current depth is {self.git.total_commits()}. "
-                )
+            if not commit_id:
+                continue
+
+            if not self.git_deepen(commit_id):
                 logging.warning(
                     "Skipping metadata extraction of the range of new commits."
                 )
                 return None
 
+        if not start:
+            logging.warning("No start commit found. Only one commit in range.")
+            assert end
+            return (self.git.get_commit(end),)
+
         commit_list = []
         for index, commit in enumerate(
             Repository(".", from_commit=start, to_commit=end).traverse_commits()
@@ -1003,6 +1071,15 @@ class Metadata:
         """Returns a list of Markdown files."""
         return self.glob_files("**/*.{markdown,mdown,mkdn,mdwn,mkd,md,mdtxt,mdtext}")
 
+    @cached_property
+    def image_files(self) -> list[Path]:
+        """Returns a list of image files.
+
+        Inspired by the list of image extensions supported by calibre's image-actions:
+        https://github.com/calibreapp/image-actions/blob/f325757/src/constants.ts#L32
+        """
+        return self.glob_files("**/*.{jpeg,jpg,png,webp,avif}")
+
     @cached_property
     def zsh_files(self) -> list[Path]:
         """Returns a list of Zsh files."""
@@ -1127,6 +1204,7 @@ class Metadata:
         - ``--target-version py311``
         - ``--target-version py312``
         - ``--target-version py313``
+        - ``--target-version py314``
 
         As mentioned in Black usage, you should `include all Python versions that you
         want your code to run under
@@ -1556,7 +1634,7 @@ class Metadata:
             else:
                 raise NotImplementedError(f"GitHub formatting for: {value!r}")
 
-        return cast(str, value)
+        return str(value)
 
     def dump(self, dialect: Dialects = Dialects.github) -> str:
         """Returns all metadata in the specified format.
@@ -1575,6 +1653,7 @@ class Metadata:
             "workflow_files": self.workflow_files,
             "doc_files": self.doc_files,
             "markdown_files": self.markdown_files,
+            "image_files": self.image_files,
             "zsh_files": self.zsh_files,
             "is_python_project": self.is_python_project,
             "package_name": self.package_name,

gha_utils/test_plan.py

@@ -17,19 +17,31 @@
 from __future__ import annotations
 
 import logging
+import os
 import re
 import shlex
 import sys
+from collections.abc import Sequence
 from dataclasses import asdict, dataclass, field
 from pathlib import Path
+from shutil import which
 from subprocess import TimeoutExpired, run
-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, render_cli_run
-from extra_platforms import Group, _TNestedReferences, current_os
+from click_extra.testing import (
+    args_cleanup,
+    regex_fullmatch_line_by_line,
+    render_cli_run,
+)
+from extra_platforms import Group, current_os
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+    from extra_platforms._types import _TNestedReferences
 
 
 class SkippedTest(Exception):
@@ -38,6 +50,20 @@ class SkippedTest(Exception):
     pass
 
 
+def _split_args(cli: str) -> list[str]:
+    """Split a string or sequence of strings into a tuple of arguments.
+
+    .. todo::
+        Evaluate better Windows CLI parsing with:
+        `w32lex <https://github.com/maxpat78/w32lex>`_.
+    """
+    if sys.platform == "win32":
+        return cli.split()
+    # For Unix platforms, we have the dedicated shlex module.
+    else:
+        return shlex.split(cli)
+
+
 @dataclass(order=True)
 class CLITestCase:
     cli_parameters: tuple[str, ...] | str = field(default_factory=tuple)
@@ -102,13 +128,7 @@ class CLITestCase:
                         # CLI parameters provided as a long string needs to be split so
                         # that each argument is a separate item in the final tuple.
                         if field_id == "cli_parameters":
-                            # XXX Maybe we should rely on a library to parse them:
-                            # https://github.com/maxpat78/w32lex
-                            if sys.platform == "win32":
-                                field_data = field_data.split()
-                            # For Unix platforms, we have the dedicated shlex module.
-                            else:
-                                field_data = shlex.split(field_data)
+                            field_data = _split_args(field_data)
                         else:
                             field_data = (field_data,)
 
@@ -147,16 +167,22 @@ class CLITestCase:
 
     def run_cli_test(
         self,
-        binary: str | Path,
+        command: Path | str,
         additional_skip_platforms: _TNestedReferences | None,
         default_timeout: float | None,
     ):
         """Run a CLI command and check its output against the test case.
 
-        ..todo::
+        The provided ``command`` can be either:
+
+        - a path to a binary or script to execute;
+        - a command name to be searched in the ``PATH``,
+        - a command line with arguments to be parsed and executed by the shell.
+
+        .. todo::
             Add support for environment variables.
 
-        ..todo::
+        .. todo::
             Add support for proper mixed <stdout>/<stderr> stream as a single,
             intertwined output.
         """
@@ -173,7 +199,28 @@ class CLITestCase:
             logging.info(f"Set default test case timeout to {default_timeout} seconds")
             self.timeout = default_timeout
 
-        clean_args = args_cleanup(binary, self.cli_parameters)
+        # Separate the command into binary file path and arguments.
+        args = []
+        if isinstance(command, str):
+            args = _split_args(command)
+            command = args[0]
+            args = args[1:]
+            # Ensure the command to execute is in PATH.
+            if not which(command):
+                raise FileNotFoundError(f"Command not found in PATH: {command!r}")
+            # Resolve the command to an absolute path.
+            command = which(command)  # type: ignore[assignment]
+            assert command is not None
+
+        # Check the binary exists and is executable.
+        binary = Path(command).resolve()
+        assert binary.exists()
+        assert binary.is_file()
+        assert os.access(binary, os.X_OK)
+
+        clean_args = args_cleanup(binary, args, self.cli_parameters)
+        logging.info(f"Run CLI command: {' '.join(clean_args)}")
+
         try:
             result = run(
                 clean_args,
@@ -265,9 +312,7 @@ class CLITestCase:
                         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"{name} does not fully match regex {regex}")
+                regex_fullmatch_line_by_line(field_data, output)
 
 
 DEFAULT_TEST_PLAN: list[CLITestCase] = [

{gha_utils-4.21.0.dist-info → gha_utils-4.23.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gha-utils
-Version: 4.21.0
+Version: 4.23.0
 Summary: ⚙️ CLI helpers for GitHub Actions + reuseable workflows
 Author-email: Kevin Deldycke <kevin@deldycke.com>
 Project-URL: Homepage, https://github.com/kdeldycke/workflows
@@ -48,18 +48,18 @@ Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
-Requires-Dist: boltons>=24.0.0
+Requires-Dist: boltons>=25.0.0
 Requires-Dist: bump-my-version<1.1.1,>=0.32.2
-Requires-Dist: click-extra~=6.0.0
-Requires-Dist: extra-platforms~=3.2.0
-Requires-Dist: packaging~=25.0
-Requires-Dist: py-walk~=0.3.3
-Requires-Dist: PyDriller~=2.6
-Requires-Dist: pyproject-metadata~=0.9.0
-Requires-Dist: pyyaml~=6.0.0
-Requires-Dist: wcmatch>=8.5
+Requires-Dist: click-extra>=6.0.3
+Requires-Dist: extra-platforms>=4.0.0
+Requires-Dist: packaging>=25.0
+Requires-Dist: py-walk>=0.3.3
+Requires-Dist: PyDriller>=2.6
+Requires-Dist: pyproject-metadata>=0.9.0
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: wcmatch>=10.0
 Provides-Extra: test
-Requires-Dist: coverage[toml]~=7.10.0; extra == "test"
+Requires-Dist: coverage[toml]~=7.11.0; extra == "test"
 Requires-Dist: pytest~=8.4.0; extra == "test"
 Requires-Dist: pytest-cases~=3.9.1; extra == "test"
 Requires-Dist: pytest-cov~=7.0.0; extra == "test"

gha_utils-4.23.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+gha_utils/__init__.py,sha256=2-HGMEacBozPv5vkkzNBw1QXVNpQS6cGdU_jNj8-AcU,866
+gha_utils/__main__.py,sha256=Dck9BjpLXmIRS83k0mghAMcYVYiMiFLltQdfRuMSP_Q,1703
+gha_utils/changelog.py,sha256=JR7iQrWjLoIOpVNe6iXQSyEii82_hM_zrYpR7QO_Uxo,5777
+gha_utils/cli.py,sha256=3mSO9qoVOkKGZARH6CSjTsyWpSodPd64uDZHHazzd_E,15289
+gha_utils/mailmap.py,sha256=oQt3m0hj-mwg7WxsuJQXWeQTFjlkqTgRNjYsUv7dlYQ,7013
+gha_utils/matrix.py,sha256=K0J-OHHEXibBTRmuCmyvscSjRGPPsGRuwp9rKnlj8KI,12486
+gha_utils/metadata.py,sha256=pUuaJPJrKgjTjbh2v2VwDGf8mkmmE9mfsCXUaWaMOBg,61750
+gha_utils/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gha_utils/test_plan.py,sha256=-Uwe1Y5xCNHuXERzGsZV3aaZvbvITNR1nxVFbIB3c1s,14573
+gha_utils-4.23.0.dist-info/METADATA,sha256=QaW2CqLZ-eHrSg5ralL0eOI_jBejUrrFCsE0NmypzGY,21421
+gha_utils-4.23.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+gha_utils-4.23.0.dist-info/entry_points.txt,sha256=8bJOwQYf9ZqsLhBR6gUCzvwLNI9f8tiiBrJ3AR0EK4o,54
+gha_utils-4.23.0.dist-info/top_level.txt,sha256=C94Blb61YkkyPBwCdM3J_JPDjWH0lnKa5nGZeZ5M6yE,10
+gha_utils-4.23.0.dist-info/RECORD,,

gha_utils-4.21.0.dist-info/RECORD

@@ -1,14 +0,0 @@
-gha_utils/__init__.py,sha256=HCe5G0ysXtBmQ8s34Mi5DeYCvYLFSPYzWcV4pPfYdGw,866
-gha_utils/__main__.py,sha256=Dck9BjpLXmIRS83k0mghAMcYVYiMiFLltQdfRuMSP_Q,1703
-gha_utils/changelog.py,sha256=JR7iQrWjLoIOpVNe6iXQSyEii82_hM_zrYpR7QO_Uxo,5777
-gha_utils/cli.py,sha256=hwvjKEUvctmtJL2aliV0dytF67uHjGVuUKv17j_lMlg,15235
-gha_utils/mailmap.py,sha256=oQt3m0hj-mwg7WxsuJQXWeQTFjlkqTgRNjYsUv7dlYQ,7013
-gha_utils/matrix.py,sha256=eBAU3bKrCif7FQ74EWhK_AwDcNUkGp8Om1NtlFdYJpI,12431
-gha_utils/metadata.py,sha256=hySTDkjPS2NMKvFlmEmpy4F7rwrjmST_ZiygmF9OOZk,58839
-gha_utils/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-gha_utils/test_plan.py,sha256=AE8Mf1vSQG5EZTytoTts-gzMwUg2Zy21gUwkMlzXT94,13394
-gha_utils-4.21.0.dist-info/METADATA,sha256=tdjkQaFwLnJUNm-3K8lOi4crw_n_HQWn-CNtW6BaD08,21420
-gha_utils-4.21.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-gha_utils-4.21.0.dist-info/entry_points.txt,sha256=8bJOwQYf9ZqsLhBR6gUCzvwLNI9f8tiiBrJ3AR0EK4o,54
-gha_utils-4.21.0.dist-info/top_level.txt,sha256=C94Blb61YkkyPBwCdM3J_JPDjWH0lnKa5nGZeZ5M6yE,10
-gha_utils-4.21.0.dist-info/RECORD,,