gha-utils 4.0.1__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.1"
+__version__ = "4.1.1"

gha_utils/changelog.py

@@ -38,9 +38,11 @@ class Changelog:
             self.content = initial_changelog
         logging.debug(f"Initial content set to:\n{self.content}")
 
-    def update(self) -> str:
+    def update(self) -> str | None:
         r"""Adds a new empty entry at the top of the changelog.
 
+        Returns ``None`` if initial changelog content has already been updated.
+
         This is designed to be used just after a new release has been tagged. And before a
         post-release version increment is applied with a call to:
 
@@ -145,7 +147,9 @@ class Changelog:
 
         logging.info("New generated section:\n" + indent(new_entry, " " * 2))
 
-        assert new_entry not in history
+        # No need to update.
+        if new_entry in history:
+            return None
 
         # Recompose full changelog with new top entry.
         return f"{changelog_header}{new_entry}{history}"

gha_utils/cli.py

@@ -25,6 +25,7 @@ from pathlib import Path
 
 from click_extra import (
     Choice,
+    Context,
     argument,
     extra_group,
     file_path,
@@ -55,6 +56,15 @@ def file_writer(filepath):
         writer.close()
 
 
+def get_header(ctx: Context):
+    """Generates metadata to be leaved as comments to the top of a file generated by this CLI."""
+    return (
+        f"# Generated by {ctx.command_path} v{__version__}"
+        " - https://github.com/kdeldycke/workflows\n"
+        f"# Timestamp: {datetime.now().isoformat()}.\n\n"
+    )
+
+
 @extra_group
 def gha_utils():
     pass
@@ -114,20 +124,16 @@ def metadata(ctx, format, overwrite, output_path):
         env_file = os.getenv("GITHUB_OUTPUT")
         if env_file and Path(env_file) != output_path:
             logging.warning(
-                "Output path is not the same as $GITHUB_OUTPUT environment variable, which is generally what we're looking to do in GitHub CI runners for other jobs to consume the produced metadata."
+                "Output path is not the same as $GITHUB_OUTPUT environment variable,"
+                " which is generally what we're looking to do in GitHub CI runners for"
+                " other jobs to consume the produced metadata."
             )
 
     dialect = Dialects(format)
     content = metadata.dump(dialect=dialect)
 
     with file_writer(output_path) as f:
-        f.write(
-            # Leave some metadata as comment.
-            f"# Generated by {ctx.command_path} v{__version__}"
-            " - https://github.com/kdeldycke/workflows.\n"
-            f"# Timestamp: {datetime.now().isoformat()}.\n"
-            f"{content}"
-        )
+        f.write(content)
 
 
 @gha_utils.command(short_help="Maintain a Markdown-formatted changelog")
@@ -147,10 +153,13 @@ def changelog(ctx, source, changelog_path):
     initial_content = None
     if source:
         logging.info(f"Read initial changelog from {source}")
-        initial_content = source.read_text()
+        initial_content = source.read_text(encoding="utf-8")
 
     changelog = Changelog(initial_content)
     content = changelog.update()
+    if not content:
+        logging.warning("Changelog already up to date. Do nothing.")
+        ctx.exit()
 
     if is_stdout(changelog_path):
         logging.info(f"Print updated results to {sys.stdout.name}")
@@ -189,7 +198,7 @@ def mailmap(ctx, source, updated_mailmap):
     initial_content = None
     if source:
         logging.info(f"Read initial mapping from {source}")
-        initial_content = source.read_text()
+        initial_content = source.read_text(encoding="utf-8")
 
     mailmap = Mailmap(initial_content)
     content = mailmap.updated_map()
@@ -200,10 +209,4 @@ def mailmap(ctx, source, updated_mailmap):
         logging.info(f"Save updated results to {updated_mailmap}")
 
     with file_writer(updated_mailmap) as f:
-        f.write(
-            # Leave some metadata as comment.
-            f"# Generated by {ctx.command_path} v{__version__}"
-            " - https://github.com/kdeldycke/workflows.\n"
-            f"# Timestamp: {datetime.now().isoformat()}.\n\n"
-            f"{content}"
-        )
+        f.write(f"{get_header(ctx)}{content}")

gha_utils/mailmap.py

@@ -68,7 +68,7 @@ class Mailmap:
 
         logging.debug(
             "Authors and committers found in Git history:\n"
-            f"{'\n'.join(sorted(contributors, key=str.casefold))}"
+            + "\n".join(sorted(contributors, key=str.casefold))
         )
         return contributors
 
@@ -94,6 +94,7 @@ class Mailmap:
 
         # Render content in .mailmap format.
         return (
-            f"{'\n'.join(header_comments)}\n\n"
-            f"{'\n'.join(sorted(mappings, key=str.casefold))}\n"
+            "\n".join(header_comments)
+            + "\n\n"
+            + "\n".join(sorted(mappings, key=str.casefold))
         )

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
@@ -466,7 +625,7 @@ class Metadata:
         ``pyproject.toml`` exists and respects the standards. ``False`` otherwise.
         """
         if self.pyproject_path.exists() and self.pyproject_path.is_file():
-            toml = tomllib.loads(self.pyproject_path.read_text())
+            toml = tomllib.loads(self.pyproject_path.read_text(encoding="utf-8"))
             try:
                 metadata = StandardMetadata.from_pyproject(toml)
                 self._is_python_project = True
@@ -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}"
@@ -940,9 +1115,13 @@ class Metadata:
         # Generate a link to the version of the package published on PyPi.
         pypi_link = ""
         if self.package_name:
-            pypi_link = f"[🐍 Available on PyPi](https://pypi.org/project/{
-                self.package_name
-            }/{version})."
+            pypi_link = (
+                "[🐍 Available on PyPi](https://pypi.org/project/"
+                + self.package_name
+                + "/"
+                + version
+                + ")."
+            )
 
         # Assemble the release notes.
         return f"{changes}\n\n{pypi_link}".strip()
@@ -982,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.
@@ -1009,10 +1191,10 @@ class Metadata:
         }
 
         logging.debug(f"Raw metadata: {metadata!r}")
-        logging.debug(f"Format metadata into {dialect} dialect.")
+        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)
 
@@ -1027,6 +1209,6 @@ class Metadata:
             assert dialect == Dialects.PLAIN
             content = repr(metadata)
 
-        logging.debug(f"Formatted metadata: {content}")
+        logging.debug(f"Formatted metadata:\n{content}")
 
         return content