gha-utils 4.0.2__py3-none-any.whl → 4.1.1__py3-none-any.whl

gha_utils/__init__.py

@@ -17,4 +17,4 @@
 
 from __future__ import annotations
 
-__version__ = "4.0.2"
+__version__ = "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.dist-info → gha_utils-4.1.1.dist-info}/METADATA

@@ -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,16 +44,15 @@ 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: 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
 Requires-Dist: wcmatch ~=8.5.2
+Requires-Dist: backports.strenum ~=1.3.1 ; python_version < "3.11"
 Requires-Dist: tomli ~=2.0.1 ; python_version < "3.11"
 
 # `gha-utils` CLI + reusable workflows

gha_utils-4.1.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+gha_utils/__init__.py,sha256=dnH1Sku0aFVGnpkcImGQfGV4Arm-81fr31vQMpLF-20,865
+gha_utils/__main__.py,sha256=Dck9BjpLXmIRS83k0mghAMcYVYiMiFLltQdfRuMSP_Q,1703
+gha_utils/changelog.py,sha256=Ny9lCe8w_6uyh8x5P_EuzgQX88j2FJYemVoi9pw_8DI,5765
+gha_utils/cli.py,sha256=PSQFbBF21qFDg-wdwHNAto0xouo6Ou7vQf1WHbD-96E,6784
+gha_utils/mailmap.py,sha256=7pkkE0G2Mg6nDQ5wAaujvE0tTBRBVVCqj1vkEps12bk,3725
+gha_utils/metadata.py,sha256=LDuUNk9RzVvr2BsgtB2Eh4wk_w9HnPiYM3OyxOQ9cXM,47115
+gha_utils/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gha_utils-4.1.1.dist-info/METADATA,sha256=4axsdRT1qYeWJyTLIDFR4FWIqsPsTQ2-DPOBSkMV6pk,17188
+gha_utils-4.1.1.dist-info/WHEEL,sha256=y4mX-SOX4fYIkonsAGA5N0Oy-8_gI4FXw5HNI1xqvWg,91
+gha_utils-4.1.1.dist-info/entry_points.txt,sha256=8bJOwQYf9ZqsLhBR6gUCzvwLNI9f8tiiBrJ3AR0EK4o,54
+gha_utils-4.1.1.dist-info/top_level.txt,sha256=C94Blb61YkkyPBwCdM3J_JPDjWH0lnKa5nGZeZ5M6yE,10
+gha_utils-4.1.1.dist-info/RECORD,,

{gha_utils-4.0.2.dist-info → gha_utils-4.1.1.dist-info}/WHEEL

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

gha_utils-4.0.2.dist-info/RECORD

@@ -1,12 +0,0 @@
-gha_utils/__init__.py,sha256=J57tBS8zsmxJUno0Sh1NJZJ8T7oXYwFbc8kqHz6RkK8,865
-gha_utils/__main__.py,sha256=Dck9BjpLXmIRS83k0mghAMcYVYiMiFLltQdfRuMSP_Q,1703
-gha_utils/changelog.py,sha256=Ny9lCe8w_6uyh8x5P_EuzgQX88j2FJYemVoi9pw_8DI,5765
-gha_utils/cli.py,sha256=PSQFbBF21qFDg-wdwHNAto0xouo6Ou7vQf1WHbD-96E,6784
-gha_utils/mailmap.py,sha256=7pkkE0G2Mg6nDQ5wAaujvE0tTBRBVVCqj1vkEps12bk,3725
-gha_utils/metadata.py,sha256=Z-DmNjjLy-3OOtbUCjV_15lmUlUoFUxO3znQ4ScPW0U,41010
-gha_utils/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-gha_utils-4.0.2.dist-info/METADATA,sha256=LUD-8xUh7G-ozgYQmlbTFyMgxPMqYw5CPkIXDfV66-w,17178
-gha_utils-4.0.2.dist-info/WHEEL,sha256=mguMlWGMX-VHnMpKOjjQidIo1ssRlCFu4a4mBpz1s2M,91
-gha_utils-4.0.2.dist-info/entry_points.txt,sha256=8bJOwQYf9ZqsLhBR6gUCzvwLNI9f8tiiBrJ3AR0EK4o,54
-gha_utils-4.0.2.dist-info/top_level.txt,sha256=C94Blb61YkkyPBwCdM3J_JPDjWH0lnKa5nGZeZ5M6yE,10
-gha_utils-4.0.2.dist-info/RECORD,,