gha-utils 4.0.2__tar.gz → 4.1.1__tar.gz

{gha_utils-4.0.2 → gha_utils-4.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: gha-utils
-Version: 4.0.2
+Version: 4.1.1
 Summary: ⚙️ CLI helpers for GitHub Actions + reuseable workflows
 Author-email: Kevin Deldycke <kevin@deldycke.com>
 Project-URL: Homepage, https://github.com/kdeldycke/workflows
@@ -44,12 +44,11 @@ Classifier: Topic :: Text Processing :: Markup :: HTML
 Classifier: Topic :: Text Processing :: Markup :: Markdown
 Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
-Requires-Python: >=3.8
+Requires-Python: >=3.8.6
 Description-Content-Type: text/markdown
-Requires-Dist: black~=24.4.2
+Requires-Dist: backports.strenum~=1.3.1; python_version < "3.11"
 Requires-Dist: bump-my-version~=0.24.0
 Requires-Dist: click-extra~=4.8.3
-Requires-Dist: mypy~=1.10.0
 Requires-Dist: packaging~=24.1
 Requires-Dist: PyDriller~=2.6
 Requires-Dist: pyproject-metadata~=0.8.0

{gha_utils-4.0.2 → gha_utils-4.1.1}/gha_utils/__init__.py

@@ -17,4 +17,4 @@
 
 from __future__ import annotations
 
-__version__ = "4.0.2"
+__version__ = "4.1.1"

{gha_utils-4.0.2 → gha_utils-4.1.1}/gha_utils/metadata.py

@@ -105,19 +105,20 @@ from itertools import product
 from pathlib import Path
 from random import randint
 from re import escape
-from typing import Any, Iterator, cast
+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 enum import Enum
+    from backports.strenum import StrEnum  # type: ignore[import-not-found]
 
-from black.mode import TargetVersion
 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 mypy.defaults import PYTHON3_VERSION_MIN
+from packaging.specifiers import SpecifierSet
 from packaging.version import Version
 from pydriller import Commit, Git, Repository  # type: ignore[import]
 from pyproject_metadata import ConfigurationError, StandardMetadata
@@ -144,11 +145,84 @@ SHORT_SHA_LENGTH = 7
 RESERVED_MATRIX_KEYWORDS = ["include", "exclude"]
 
 
-class Dialects(Enum):
-    """Dialects in which metadata can be formatted to."""
+WorkflowEvent = StrEnum(
+    "WorkflowEvent",
+    (
+        "branch_protection_rule",
+        "check_run",
+        "check_suite",
+        "create",
+        "delete",
+        "deployment",
+        "deployment_status",
+        "discussion",
+        "discussion_comment",
+        "fork",
+        "gollum",
+        "issue_comment",
+        "issues",
+        "label",
+        "merge_group",
+        "milestone",
+        "page_build",
+        "project",
+        "project_card",
+        "project_column",
+        "public",
+        "pull_request",
+        "pull_request_comment",
+        "pull_request_review",
+        "pull_request_review_comment",
+        "pull_request_target",
+        "push",
+        "registry_package",
+        "release",
+        "repository_dispatch",
+        "schedule",
+        "status",
+        "watch",
+        "workflow_call",
+        "workflow_dispatch",
+        "workflow_run",
+    ),
+)
+"""Workflow events that cause a workflow to run.
+
+`List of events
+<https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows>`_.
+"""
+
+
+Dialects = StrEnum("Dialects", ("github", "plain"))
+"""Dialects in which metadata can be formatted to."""
+
 
-    GITHUB = "github"
-    PLAIN = "plain"
+class TargetVersion(StrEnum):
+    """List of Python 3 minor versions supported by Black.
+
+    `Mirrors official implementation from black.mode.TargetVersion
+    <https://github.com/psf/black/blob/main/src/black/mode.py>`_.
+    """
+
+    PY33 = "3.3"
+    PY34 = "3.4"
+    PY35 = "3.5"
+    PY36 = "3.6"
+    PY37 = "3.7"
+    PY38 = "3.8"
+    PY39 = "3.9"
+    PY310 = "3.10"
+    PY311 = "3.11"
+    PY312 = "3.12"
+    PY313 = "3.13"
+
+
+MYPY_VERSION_MIN: Final = (3, 8)
+"""Earliest version supported by Mypy's ``--python-version 3.x`` parameter.
+
+`Sourced from Mypy original implementation
+<https://github.com/python/mypy/blob/master/mypy/defaults.py>`_.
+"""
 
 
 class Matrix(dict):
@@ -192,9 +266,11 @@ class Metadata:
               id: project-metadata
               env:
                 GITHUB_CONTEXT: ${{ toJSON(github) }}
-              run: >
-                python -c "$(curl -fsSL
-                https://raw.githubusercontent.com/kdeldycke/workflows/main/.github/metadata.py)"
+              run: |
+                uv run gha-utils --verbosity DEBUG metadata --overwrite "$GITHUB_OUTPUT"
+
+        .. todo::
+            Try to remove reliance on GitHub context entirely so we can eliminate the JSON/env hack above.
         """
         if "GITHUB_CONTEXT" not in os.environ:
             if self.in_ci_env:
@@ -209,6 +285,16 @@ class Metadata:
         logging.debug(json.dumps(context, indent=4))
         return context
 
+    def git_stash_count(self, git_repo: Git) -> int:
+        """Returns the number of stashes."""
+        count = int(
+            git_repo.repo.git.rev_list(
+                "--walk-reflogs", "--ignore-missing", "--count", "refs/stash"
+            )
+        )
+        logging.debug(f"Number of stashes in repository: {count}")
+        return count
+
     def commit_matrix(self, commits: Iterable[Commit] | None) -> Matrix | None:
         """Pre-compute a matrix of commits.
 
@@ -247,52 +333,117 @@ class Metadata:
         if not commits:
             return None
 
-        # Save the initial commit reference and SHA of the repository. The reference is
-        # either the canonical active branch name (i.e. ``main``), or the commit SHA if
-        # the current HEAD commit is detached from a branch.
         git = Git(".")
-        init_sha = git.repo.head.commit.hexsha
-        if git.repo.head.is_detached:
-            init_ref = init_sha
+        current_commit = git.repo.head.commit.hexsha
+
+        # Check if we need to get back in time in the Git log and browse past commits.
+        if len(commits) == 1:  # type: ignore[arg-type]
+            # Is the current commit the one we're looking for?
+            past_commit_lookup = bool(
+                current_commit != commits[0].hash  # type: ignore[index]
+            )
+        # If we have multiple commits then yes, we need to look for past commits.
         else:
-            init_ref = git.repo.active_branch.name
+            past_commit_lookup = True
 
-        sha_list = []
-        include_list = []
-        for commit in commits:
-            sha = commit.hash
+        # We need to go back in time, but first save the current state of the
+        # repository.
+        if past_commit_lookup:
+            logging.debug(
+                "We need to look into the commit history. Inspect the initial state of the repository."
+            )
 
-            # Checkout the target commit so we can read the version associated with it,
-            # but stash local changes first. Do not perform the stash/checkout dance if
-            # the repository is already at the target commit.
-            need_checkout = bool(git.repo.head.commit.hexsha != sha)
-            if need_checkout and not self.in_ci_env:
+            if not self.in_ci_env:
                 raise RuntimeError(
                     "Local repository manipulations only allowed in CI environment"
                 )
-            if need_checkout:
-                git.repo.git.stash()
-                git.checkout(sha)
+
+            # Save the initial commit reference and SHA of the repository. The reference is
+            # either the canonical active branch name (i.e. ``main``), or the commit SHA if
+            # the current HEAD commit is detached from a branch.
+            if git.repo.head.is_detached:
+                init_ref = current_commit
+            else:
+                init_ref = git.repo.active_branch.name
+            logging.debug(f"Initial commit reference: {init_ref}")
+
+            # Try to stash local changes and check if we'll need to unstash them later.
+            counter_before = self.git_stash_count(git)
+            logging.debug("Try to stash local changes before our series of checkouts.")
+            git.repo.git.stash()
+            counter_after = self.git_stash_count(git)
+            logging.debug(
+                f"Stash counter changes after 'git stash' command: {counter_before} -> {counter_after}"
+            )
+            assert counter_after >= counter_before
+            need_unstash = bool(counter_after > counter_before)
+            logging.debug(f"Need to unstash after checkouts: {need_unstash}")
+
+        else:
+            init_ref = None
+            need_unstash = False
+            logging.debug(
+                f"No need to look into the commit history: repository is already checked out at {current_commit}"
+            )
+
+        sha_list = []
+        include_list = []
+        for commit in commits:
+            if past_commit_lookup:
+                logging.debug(f"Checkout to commit {commit.hash}")
+                git.checkout(commit.hash)
+
+            logging.debug(f"Extract project version at commit {commit.hash}")
             current_version = Metadata.get_current_version()
-            if need_checkout:
-                git.repo.git.stash("pop")
 
-            sha_list.append(sha)
+            sha_list.append(commit.hash)
             include_list.append({
-                "commit": sha,
-                "short_sha": sha[:SHORT_SHA_LENGTH],
+                "commit": commit.hash,
+                "short_sha": commit.hash[:SHORT_SHA_LENGTH],
                 "current_version": current_version,
             })
 
-        # Restore the repository to its initial commit if its not in the initial state.
-        if git.repo.head.commit.hexsha != init_sha:
+        # Restore the repository to its initial state.
+        if past_commit_lookup:
+            logging.debug(f"Restore repository to {init_ref}.")
             git.checkout(init_ref)
+            if need_unstash:
+                logging.debug("Unstash local changes that were previously saved.")
+                git.repo.git.stash("pop")
 
         return Matrix({
             "commit": sha_list,
             "include": include_list,
         })
 
+    @cached_property
+    def event_type(self) -> WorkflowEvent | None:  # type: ignore[valid-type]
+        """Returns the type of event that triggered the workflow run.
+
+        .. caution::
+            This property is based on a crude heuristics as it only looks at the value
+            of the ``GITHUB_BASE_REF`` environment variable. Which is `only set when
+            the event that triggers a workflow run is either pull_request or pull_request_target
+            <https://docs.github.com/en/actions/learn-github-actions/variables#default-environment-variables>`_.
+
+        .. todo::
+            Add detection of all workflow trigger events.
+        """
+        if not self.in_ci_env:
+            logging.warning(
+                "Cannot guess event type because we're not in a CI environment."
+            )
+            return None
+        if "GITHUB_BASE_REF" not in os.environ:
+            logging.warning(
+                "Cannot guess event type because no GITHUB_BASE_REF env var found."
+            )
+            return None
+
+        if bool(os.environ.get("GITHUB_BASE_REF")):
+            return WorkflowEvent.pull_request
+        return WorkflowEvent.push
+
     @cached_property
     def commit_range(self) -> tuple[str, str] | None:
         """Range of commits bundled within the triggering event.
@@ -306,8 +457,8 @@ class Metadata:
         request that is merged upstream but we'd like to produce artifacts (builds,
         packages, etc.) for each individual commit.
 
-        The default ``GITHUB_SHA`` environment variable is useless as it only points to
-        the last commit. We need to inspect the commit history to find all new one. New
+        The default ``GITHUB_SHA`` environment variable is not enough as it only points to
+        the last commit. We need to inspect the commit history to find all new ones. New
         commits needs to be fetched differently in ``push`` and ``pull_requests``
         events.
 
@@ -316,22 +467,30 @@ class Metadata:
             - https://stackoverflow.com/a/67204539
             - https://stackoverflow.com/a/62953566
             - https://stackoverflow.com/a/61861763
+
+        .. todo::
+            Refactor so we can get rid of ``self.github_context``. Maybe there's enough metadata lying around in
+            the environment variables that we can inspect the git history and find the commit range.
         """
-        if not self.github_context:
+        if not self.github_context or not self.event_type:
             return None
         # Pull request event.
-        if self.github_context["base_ref"]:
-            start = f"origin/{self.github_context['base_ref']}"
+        if self.event_type in (
+            WorkflowEvent.pull_request,
+            WorkflowEvent.pull_request_target,
+        ):
+            base_ref = os.environ["GITHUB_BASE_REF"]
+            assert base_ref
+            start = f"origin/{base_ref}"
             # 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"]
-            end = self.github_context["sha"]
-        logging.debug("--- Commit range ---")
-        logging.debug(f"Range start: {start}")
-        logging.debug(f"Range end: {end}")
+            end = os.environ["GITHUB_SHA"]
+            assert end
+        logging.debug(f"Commit range: {start} -> {end}")
         return start, end
 
     @cached_property
@@ -518,15 +677,31 @@ class Metadata:
     def py_target_versions(self) -> tuple[Version, ...] | None:
         """Generates the list of Python target versions.
 
-        This is based on Black's support matrix.
+        Only takes ``major.minor`` variations into account. Smaller version dimensions
+        are ignored, so a package depending on ``3.8.6`` will keep ``3.8`` as a Python
+        target.
         """
         if self.pyproject and self.pyproject.requires_python:
-            minor_range = sorted(v.value for v in TargetVersion)
-            black_range = (Version(f"3.{minor}") for minor in minor_range)
+            # Dumb down specifiers' lower bounds to their major.minor version.
+            spec_list = []
+            for spec in self.pyproject.requires_python:
+                if spec.operator in (">=", ">"):
+                    major, minor, _ = Version(spec.version).release
+                    new_spec = f"{spec.operator}{major}.{minor}"
+                else:
+                    new_spec = str(spec)
+                spec_list.append(new_spec)
+            relaxed_specs = SpecifierSet(",".join(spec_list))
+            logging.debug(
+                "Relax Python requirements from "
+                f"{self.pyproject.requires_python} to {relaxed_specs}."
+            )
+
+            # Iterate through Python version support.
             return tuple(
-                version
-                for version in black_range
-                if self.pyproject.requires_python.contains(version)
+                Version(target)
+                for target in tuple(TargetVersion)
+                if relaxed_specs.contains(target)
             )
         return None
 
@@ -580,12 +755,12 @@ class Metadata:
     def mypy_params(self) -> str | None:
         """Generates `mypy` parameters.
 
-        Mypy needs to be fed with this parameter: ``--python-version x.y``.
+        Mypy needs to be fed with this parameter: ``--python-version 3.x``.
         """
         if self.py_target_versions:
             # Compare to Mypy's lowest supported version of Python dialect.
             major, minor = max(
-                PYTHON3_VERSION_MIN,
+                MYPY_VERSION_MIN,
                 min((v.major, v.minor) for v in self.py_target_versions),
             )
             return f"--python-version {major}.{minor}"
@@ -986,7 +1161,10 @@ class Metadata:
 
         return cast(str, value)
 
-    def dump(self, dialect: Dialects = Dialects.GITHUB) -> str:
+    def dump(
+        self,
+        dialect: Dialects = Dialects.github,  # type: ignore[valid-type]
+    ) -> str:
         """Returns all metadata in the specified format.
 
         Defaults to GitHub dialect.
@@ -1016,7 +1194,7 @@ class Metadata:
         logging.debug(f"Format metadata into {dialect} format.")
 
         content = ""
-        if dialect == Dialects.GITHUB:
+        if dialect == Dialects.github:
             for env_name, value in metadata.items():
                 env_value = self.format_github_value(value)
 

{gha_utils-4.0.2 → gha_utils-4.1.1}/gha_utils.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: gha-utils
-Version: 4.0.2
+Version: 4.1.1
 Summary: ⚙️ CLI helpers for GitHub Actions + reuseable workflows
 Author-email: Kevin Deldycke <kevin@deldycke.com>
 Project-URL: Homepage, https://github.com/kdeldycke/workflows
@@ -44,12 +44,11 @@ Classifier: Topic :: Text Processing :: Markup :: HTML
 Classifier: Topic :: Text Processing :: Markup :: Markdown
 Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
-Requires-Python: >=3.8
+Requires-Python: >=3.8.6
 Description-Content-Type: text/markdown
-Requires-Dist: black~=24.4.2
+Requires-Dist: backports.strenum~=1.3.1; python_version < "3.11"
 Requires-Dist: bump-my-version~=0.24.0
 Requires-Dist: click-extra~=4.8.3
-Requires-Dist: mypy~=1.10.0
 Requires-Dist: packaging~=24.1
 Requires-Dist: PyDriller~=2.6
 Requires-Dist: pyproject-metadata~=0.8.0

{gha_utils-4.0.2 → gha_utils-4.1.1}/gha_utils.egg-info/requires.txt

@@ -1,11 +1,10 @@
-black~=24.4.2
 bump-my-version~=0.24.0
 click-extra~=4.8.3
-mypy~=1.10.0
 packaging~=24.1
 PyDriller~=2.6
 pyproject-metadata~=0.8.0
 wcmatch~=8.5.2
 
 [:python_version < "3.11"]
+backports.strenum~=1.3.1
 tomli~=2.0.1

{gha_utils-4.0.2 → gha_utils-4.1.1}/pyproject.toml

@@ -1,9 +1,11 @@
 [project]
 # Docs: https://packaging.python.org/en/latest/guides/writing-pyproject-toml/
 name = "gha-utils"
-version = "4.0.2"
+version = "4.1.1"
 # Python versions and their status: https://devguide.python.org/versions/
-requires-python = ">= 3.8"
+# XXX 3.8 is not enough and we need to bump requirements to 3.8.6 because of:
+# https://github.com/clbarnes/backports.strenum/issues/1
+requires-python = ">= 3.8.6"
 description = "⚙️ CLI helpers for GitHub Actions + reuseable workflows"
 authors = [{ name = "Kevin Deldycke", email = "kevin@deldycke.com" }]
 readme = "readme.md"
@@ -69,10 +71,9 @@ classifiers = [
     'Typing :: Typed',
 ]
 dependencies = [
-    "black ~= 24.4.2",
+    "backports.strenum ~= 1.3.1 ; python_version < '3.11'",
     "bump-my-version ~= 0.24.0",
     "click-extra ~= 4.8.3",
-    "mypy ~= 1.10.0",
     "packaging ~= 24.1",
     "PyDriller ~= 2.6",
     "pyproject-metadata ~= 0.8.0",
@@ -94,7 +95,7 @@ gha-utils = "gha_utils.__main__:main"
 include = ["gha_utils"]
 
 [tool.bumpversion]
-current_version = "4.0.2"
+current_version = "4.1.1"
 allow_dirty = true
 ignore_missing_files = true