gha-utils 4.21.0__tar.gz → 4.23.0__tar.gz

{gha_utils-4.21.0 → gha_utils-4.23.0}/PKG-INFO

@@ -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.21.0 → gha_utils-4.23.0}/gha_utils/__init__.py

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

{gha_utils-4.21.0 → gha_utils-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-4.21.0 → gha_utils-4.23.0}/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-4.21.0 → gha_utils-4.23.0}/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-4.21.0 → gha_utils-4.23.0}/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 → gha_utils-4.23.0}/gha_utils.egg-info/PKG-INFO

@@ -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.21.0 → gha_utils-4.23.0}/gha_utils.egg-info/requires.txt

@@ -1,16 +1,16 @@
-boltons>=24.0.0
+boltons>=25.0.0
 bump-my-version<1.1.1,>=0.32.2
-click-extra~=6.0.0
-extra-platforms~=3.2.0
-packaging~=25.0
-py-walk~=0.3.3
-PyDriller~=2.6
-pyproject-metadata~=0.9.0
-pyyaml~=6.0.0
-wcmatch>=8.5
+click-extra>=6.0.3
+extra-platforms>=4.0.0
+packaging>=25.0
+py-walk>=0.3.3
+PyDriller>=2.6
+pyproject-metadata>=0.9.0
+pyyaml>=6.0.3
+wcmatch>=10.0
 
 [test]
-coverage[toml]~=7.10.0
+coverage[toml]~=7.11.0
 pytest~=8.4.0
 pytest-cases~=3.9.1
 pytest-cov~=7.0.0

{gha_utils-4.21.0 → gha_utils-4.23.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 # Docs: https://packaging.python.org/en/latest/guides/writing-pyproject-toml/
 name = "gha-utils"
-version = "4.21.0"
+version = "4.23.0"
 # Python versions and their status: https://devguide.python.org/versions/
 requires-python = ">= 3.11"
 description = "⚙️ CLI helpers for GitHub Actions + reuseable workflows"
@@ -70,31 +70,45 @@ classifiers = [
     'Topic :: Utilities',
     'Typing :: Typed',
 ]
+# Semantic versioning works in theory. In practice, it is hard to guarantee.
+# That's why we rely on >= specifier instead of ~= to relax constraints. This gives more freedom to packagers to
+# release hotfixes for security vulnerabilities in the future.
+# See also discussion about upper limits at: https://iscinumpy.dev/post/bound-version-constraints/#tldr
+# All minimal version choice are documented. Reasons to bump a minimal version are:
+# - bug fixes,
+# - security fixes,
+# - new code path we depends on,
+# - aligns minimal Python requirements to ours,
+# - adds new explicit support Python version.
 dependencies = [
-    # Loose version to let click-extra set its own stricter dependency.
-    "boltons >= 24.0.0",
-    # Dependency version is more relaxed on bump-my-version to prevent chicken and egg
-    # while releasing gha-utils itself.
+    # boltons 25.0.0 is the first version to support Python 3.13.
+    "boltons >= 25.0.0",
     # v0.32.2 is the first fixing an issue preventing compilation with Nuitka.
     # v1.1.1 and later have some regressions: see https://github.com/callowayproject/bump-my-version/issues/331
     "bump-my-version >= 0.32.2, < 1.1.1",
-    # Click Extra 6.0.0 fix an isue with --version option.
-    "click-extra ~= 6.0.0",
-    "extra-platforms ~= 3.2.0",
-    "packaging ~= 25.0",
-    # In the future, replace py-walk with wcmatch once the latter supports gitignore files:
+    # Click Extra 6.0.3 fix the regex_fullmatch_line_by_line() function we rely on.
+    "click-extra >= 6.0.3",
+    # Extra Platforms 4.0.0 is the first one to support Python 3.14.
+    "extra-platforms >= 4.0.0",
+    # v25.0 is the first version we used when we last changed the requirement.
+    "packaging >= 25.0",
+    # v0.3.3 is the first version we used.
+    # XXX In the future, replace py-walk with wcmatch once the latter supports gitignore files:
     # https://github.com/facelessuser/wcmatch/issues/226
-    "py-walk ~= 0.3.3",
-    "PyDriller ~= 2.6",
-    "pyproject-metadata ~= 0.9.0",
-    "pyyaml ~= 6.0.0",
-    # Loose version to let click-extra set its own stricter dependency.
-    "wcmatch >= 8.5",
+    "py-walk >= 0.3.3",
+    # PyDriller 2.6.0 is the first version we used when we last changed the requirement.
+    "PyDriller >= 2.6",
+    # v0.9.0 supports the latest metadata specifications.
+    "pyproject-metadata >= 0.9.0",
+    # PyYAML 6.0.3 is the first version to support Python 3.14.
+    "pyyaml >= 6.0.3",
+    # wcmatch 10.0 fix some inconsistencies in globbing and symlinks.
+    "wcmatch >= 10.0",
 ]
 
 [project.optional-dependencies]
 test = [
-    "coverage [toml] ~= 7.10.0",
+    "coverage [toml] ~= 7.11.0",
     "pytest ~= 8.4.0",
     "pytest-cases ~= 3.9.1",
     "pytest-cov ~= 7.0.0",
@@ -146,7 +160,7 @@ addopts = [
 xfail_strict = true
 
 [tool.bumpversion]
-current_version = "4.21.0"
+current_version = "4.23.0"
 allow_dirty = true
 ignore_missing_files = true
 

{gha_utils-4.21.0 → gha_utils-4.23.0}/tests/test_metadata.py

@@ -163,6 +163,9 @@ expected = {
         "changelog.md",
         "readme.md",
     ],
+    "image_files": [
+        "docs/assets/repo-workflow-permissions.png",
+    ],
     "zsh_files": [],
     "is_python_project": True,
     "package_name": "gha-utils",