gha-utils 4.0.1__py3-none-any.whl

gha_utils/__init__.py

@@ -0,0 +1,20 @@
+# Copyright Kevin Deldycke <kevin@deldycke.com> and contributors.
+#
+# This program is Free Software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
+"""Expose package-wide elements."""
+
+from __future__ import annotations
+
+__version__ = "4.0.1"

gha_utils/__main__.py

@@ -0,0 +1,49 @@
+# Copyright Kevin Deldycke <kevin@deldycke.com> and contributors.
+#
+# This program is Free Software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
+"""Allow the module to be run as a CLI. I.e.:
+
+.. code-block:: shell-session
+
+    $ python -m gha_utils
+"""
+
+from __future__ import annotations
+
+
+def main():
+    """Execute the CLI but force its name to not let Click defaults to:
+
+    .. code-block:: shell-session
+        $ python -m gha_utils --version
+        python -m gha_utils, version 4.0.0
+
+    Indirection via this ``main()`` method was `required to reconcile
+    <https://github.com/python-poetry/poetry/issues/5981>`_:
+
+        - plain inline package call: ``python -m gha_utils``,
+        - Poetry's script entry point: ``gha-utils = 'gha_utils.__main__:main``,
+        - Nuitka's main module invocation requirement:
+          ``python -m nuitka (...) gha_utils/__main__.py``
+
+    That way we can deduce all three cases from the entry point.
+    """
+    from gha_utils.cli import gha_utils
+
+    gha_utils(prog_name=gha_utils.name)
+
+
+if __name__ == "__main__":
+    main()

gha_utils/changelog.py

@@ -0,0 +1,151 @@
+# Copyright Kevin Deldycke <kevin@deldycke.com> and contributors.
+#
+# This program is Free Software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
+
+from __future__ import annotations
+
+import logging
+import re
+import sys
+from pathlib import Path
+from textwrap import indent
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib  # type: ignore[import]
+
+
+class Changelog:
+    """Helpers to manipulate changelog files written in Markdown."""
+
+    def __init__(self, initial_changelog: str | None = None) -> None:
+        if not initial_changelog:
+            self.content = "# Changelog\n"
+        else:
+            self.content = initial_changelog
+        logging.debug(f"Initial content set to:\n{self.content}")
+
+    def update(self) -> str:
+        r"""Adds a new empty entry at the top of the changelog.
+
+        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:
+
+        ```shell-session
+        $ bump-my-version bump --verbose patch
+        Starting BumpVersion 0.5.1.dev6
+        Reading config file pyproject.toml:
+        Specified version (2.17.5) does not match last tagged version (2.17.4)
+        Parsing version '2.17.5' using '(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)'
+        Parsed the following values: major=2, minor=17, patch=5
+        Attempting to increment part 'patch'
+        Values are now: major=2, minor=17, patch=6
+        New version will be '2.17.6'
+        Dry run active, won't touch any files.
+        Asserting files ./changelog.md contain the version string...
+        Found '[2.17.5 (unreleased)](' in ./changelog.md at line 2:
+        ## [2.17.5 (unreleased)](https://github.com/kdeldycke/workflows/compare/v2.17.4...main)
+        Would change file ./changelog.md:
+        *** before ./changelog.md
+        --- after ./changelog.md
+        ***************
+        *** 1,6 ****
+          # Changelog
+
+        ! ## [2.17.5 (unreleased)](https://github.com/kdeldycke/workflows/compare/v2.17.4...main)
+
+          > \[!IMPORTANT\]
+          > This version is not released yet and is under active development.
+        --- 1,6 ----
+          # Changelog
+
+        ! ## [2.17.6 (unreleased)](https://github.com/kdeldycke/workflows/compare/v2.17.4...main)
+
+          > \[!IMPORTANT\]
+          > This version is not released yet and is under active development.
+        Would write to config file pyproject.toml:
+        *** before pyproject.toml
+        --- after pyproject.toml
+        ***************
+        *** 1,5 ****
+          [tool.bumpversion]
+        ! current_version = "2.17.5"
+          allow_dirty = true
+
+          [[tool.bumpversion.files]]
+        --- 1,5 ----
+          [tool.bumpversion]
+        ! current_version = "2.17.6"
+          allow_dirty = true
+
+          [[tool.bumpversion.files]]
+        Would not commit
+        Would not tag since we are not committing
+        ```
+        """
+        # Extract current version as defined by bump-my-version.
+        config_file = Path("./pyproject.toml").resolve()
+        logging.info(f"Open {config_file}")
+        config = tomllib.loads(config_file.read_text(encoding="utf-8"))
+        current_version = config["tool"]["bumpversion"]["current_version"]
+        logging.info(f"Current version: {current_version}")
+        assert current_version
+
+        assert current_version in self.content
+
+        # Analyse the current changelog.
+        SECTION_START = "##"
+        changelog_header, last_entry, past_entries = self.content.split(
+            SECTION_START, 2
+        )
+
+        # Derive the release template from the last entry.
+        DATE_REGEX = r"\d{4}\-\d{2}\-\d{2}"
+        VERSION_REGEX = r"\d+\.\d+\.\d+"
+
+        # Replace the release date with the unreleased tag.
+        new_entry = re.sub(DATE_REGEX, "unreleased", last_entry, count=1)
+
+        # Update GitHub's comparison URL to target the main branch.
+        new_entry = re.sub(
+            rf"v{VERSION_REGEX}\.\.\.v{VERSION_REGEX}",
+            f"v{current_version}...main",
+            new_entry,
+            count=1,
+        )
+
+        # Replace the whole paragraph of changes by a notice message. The paragraph is
+        # identified as starting by a blank line, at which point everything gets
+        # replaced.
+        new_entry = re.sub(
+            r"\n\n.*",
+            "\n\n"
+            "> \[!IMPORTANT\]\n"
+            "> This version is not released yet and is under active development.\n\n",
+            new_entry,
+            flags=re.MULTILINE | re.DOTALL,
+        )
+
+        # Prefix entries with section marker.
+        new_entry = f"{SECTION_START}{new_entry}"
+        history = f"{SECTION_START}{last_entry}{SECTION_START}{past_entries}"
+
+        logging.info("New generated section:\n" + indent(new_entry, " " * 2))
+
+        assert new_entry not in history
+
+        # Recompose full changelog with new top entry.
+        return f"{changelog_header}{new_entry}{history}"

gha_utils/cli.py

@@ -0,0 +1,209 @@
+# Copyright Kevin Deldycke <kevin@deldycke.com> and contributors.
+#
+# This program is Free Software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from contextlib import contextmanager
+from datetime import datetime
+from pathlib import Path
+
+from click_extra import (
+    Choice,
+    argument,
+    extra_group,
+    file_path,
+    option,
+    pass_context,
+    path,
+)
+
+from . import __version__
+from .changelog import Changelog
+from .mailmap import Mailmap
+from .metadata import Dialects, Metadata
+
+
+def is_stdout(filepath):
+    return str(filepath) == "-"
+
+
+@contextmanager
+def file_writer(filepath):
+    """A context-aware file writer which default to stdout if no path is
+    provided."""
+    if is_stdout(filepath):
+        yield sys.stdout
+    else:
+        writer = filepath.open("w")
+        yield writer
+        writer.close()
+
+
+@extra_group
+def gha_utils():
+    pass
+
+
+@gha_utils.command(short_help="Output project metadata")
+@option(
+    "--format",
+    type=Choice(tuple(item.value for item in Dialects), case_sensitive=False),
+    default="github",
+    help="Rendering format of the metadata.",
+)
+@option(
+    "--overwrite",
+    "--force",
+    "--replace",
+    is_flag=True,
+    default=False,
+    help="Allow output target file to be silently wiped out if it already exists.",
+)
+@argument(
+    "output_path",
+    type=file_path(writable=True, resolve_path=True, allow_dash=True),
+    default="-",
+)
+@pass_context
+def metadata(ctx, format, overwrite, output_path):
+    """Dump project metadata to a file.
+
+    By default the metadata produced are displayed directly to the console output.
+    So `gha-utils metadata` is the same as a call to `gha-utils metadata -`. To have the results written
+    in a file on disk, specify the output file like so: `gha-utils metadata dump.txt`.
+
+    For GitHub you want to output to the standard environment file pointed to by the `$GITHUB_OUTPUT` variable. I.e.:
+
+        $ gha-utils metadata --format github "$GITHUB_OUTPUT"
+    """
+    if is_stdout(output_path):
+        if overwrite:
+            logging.warning("Ignore the --overwrite/--force/--replace option.")
+        logging.info(f"Print metadata to {sys.stdout.name}")
+    else:
+        logging.info(f"Dump all metadata to {output_path}")
+
+        if output_path.exists():
+            msg = "Target file exist and will be overwritten."
+            if overwrite:
+                logging.warning(msg)
+            else:
+                logging.critical(msg)
+                ctx.exit(2)
+
+    metadata = Metadata()
+
+    # Output a warning in GitHub runners if metadata are not saved to $GITHUB_OUTPUT.
+    if metadata.in_ci_env:
+        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."
+            )
+
+    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}"
+        )
+
+
+@gha_utils.command(short_help="Maintain a Markdown-formatted changelog")
+@option(
+    "--source",
+    type=path(exists=True, readable=True, resolve_path=True),
+    default="changelog.md",
+    help="Changelog source file in Markdown format.",
+)
+@argument(
+    "changelog_path",
+    type=file_path(writable=True, resolve_path=True, allow_dash=True),
+    default="-",
+)
+@pass_context
+def changelog(ctx, source, changelog_path):
+    initial_content = None
+    if source:
+        logging.info(f"Read initial changelog from {source}")
+        initial_content = source.read_text()
+
+    changelog = Changelog(initial_content)
+    content = changelog.update()
+
+    if is_stdout(changelog_path):
+        logging.info(f"Print updated results to {sys.stdout.name}")
+    else:
+        logging.info(f"Save updated results to {changelog_path}")
+
+    with file_writer(changelog_path) as f:
+        f.write(content)
+
+
+@gha_utils.command(short_help="Sync Git's .mailmap at project's root")
+@option(
+    "--source",
+    type=path(exists=True, readable=True, resolve_path=True),
+    default=".mailmap",
+    help=".mailmap source file to be updated with missing contributors.",
+)
+@argument(
+    "updated_mailmap",
+    type=file_path(writable=True, resolve_path=True, allow_dash=True),
+    default="-",
+)
+@pass_context
+def mailmap(ctx, source, updated_mailmap):
+    """Update a ``.mailmap`` file with missing contributors found in Git commit history.
+
+    By default the existing .mailmap is read to be used as initial mapping. To which missing contributors are added.
+    Then the results are printed to the console output. So `gha-utils mailmap` is the same as a call to `gha-utils mailmap --source .mailmap -`.
+
+    To have the updated results written
+    to a file on disk, specify the output file like so: `gha-utils mailmap .mailmap`.
+
+    The updated results are quite dumb, so it is advised to identify potential duplicate identities,
+    then regroup them by hand.
+    """
+    initial_content = None
+    if source:
+        logging.info(f"Read initial mapping from {source}")
+        initial_content = source.read_text()
+
+    mailmap = Mailmap(initial_content)
+    content = mailmap.updated_map()
+
+    if is_stdout(updated_mailmap):
+        logging.info(f"Print updated results to {sys.stdout.name}")
+    else:
+        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}"
+        )

gha_utils/mailmap.py

@@ -0,0 +1,99 @@
+# Copyright Kevin Deldycke <kevin@deldycke.com> and contributors.
+#
+# This program is Free Software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
+
+from __future__ import annotations
+
+import logging
+import sys
+from functools import cached_property
+from subprocess import run
+from textwrap import dedent
+
+
+class Mailmap:
+    """Helpers to manipulate ``.mailmap`` file.
+
+    The ``.mailmap`` files expected to be found in the root of repository.
+    """
+
+    def __init__(self, initial_mailmap: str | None = None) -> None:
+        if not initial_mailmap:
+            # Initialize empty .mailmap with pointers to reference documentation.
+            self.content = dedent(
+                """\
+                # Format is:
+                #   Preferred Name <preferred e-mail>  Other Name <other e-mail>
+                #
+                # Reference: https://git-scm.com/docs/git-blame#_mapping_authors
+                """,
+            )
+        else:
+            self.content = initial_mailmap
+        logging.debug(f"Initial content set to:\n{self.content}")
+
+    @cached_property
+    def git_contributors(self) -> set[str]:
+        """Returns the set of all constributors found in the Git commit history.
+
+        No normalization happens: all variations of authors and committers strings attached to all commits are considered.
+
+        For format output syntax, see:
+        https://git-scm.com/docs/pretty-formats#Documentation/pretty-formats.txt-emaNem
+        """
+        contributors = set()
+
+        git_cli = ("git", "log", "--pretty=format:%aN <%aE>%n%cN <%cE>")
+        logging.debug(f"Run: {' '.join(git_cli)}")
+        process = run(git_cli, capture_output=True, encoding="utf-8")
+
+        # Parse git CLI output.
+        if process.returncode:
+            sys.exit(process.stderr)
+        for line in process.stdout.splitlines():
+            if line.strip():
+                contributors.add(line)
+
+        logging.debug(
+            "Authors and committers found in Git history:\n"
+            f"{'\n'.join(sorted(contributors, key=str.casefold))}"
+        )
+        return contributors
+
+    def updated_map(self):
+        """Add all missing contributors from commit history to mailmap.
+
+        This method will refrain from adding contributors already registered as aliases.
+        """
+        # Extract comments in .mailmap header and keep mapping lines.
+        header_comments = []
+        mappings = set()
+        for line in self.content.splitlines():
+            if line.startswith("#"):
+                header_comments.append(line)
+            elif line.strip():
+                mappings.add(line)
+
+        # Add all missing contributors to the mail mapping.
+        for contributor in self.git_contributors:
+            if contributor not in self.content:
+                logging.debug(f"{contributor!r} not found in original content, add it.")
+                mappings.add(contributor)
+
+        # Render content in .mailmap format.
+        return (
+            f"{'\n'.join(header_comments)}\n\n"
+            f"{'\n'.join(sorted(mappings, key=str.casefold))}\n"
+        )