gha-utils 4.1.3__tar.gz → 4.2.0__tar.gz

{gha_utils-4.1.3 → gha_utils-4.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: gha-utils
-Version: 4.1.3
+Version: 4.2.0
 Summary: ⚙️ CLI helpers for GitHub Actions + reuseable workflows
 Author-email: Kevin Deldycke <kevin@deldycke.com>
 Project-URL: Homepage, https://github.com/kdeldycke/workflows
@@ -47,6 +47,7 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.8.6
 Description-Content-Type: text/markdown
 Requires-Dist: backports.strenum~=1.3.1; python_version < "3.11"
+Requires-Dist: boltons~=24.0.0
 Requires-Dist: bump-my-version~=0.24.0
 Requires-Dist: click-extra~=4.8.3
 Requires-Dist: packaging~=24.1

{gha_utils-4.1.3 → gha_utils-4.2.0}/gha_utils/__init__.py

@@ -17,4 +17,4 @@
 
 from __future__ import annotations
 
-__version__ = "4.1.3"
+__version__ = "4.2.0"

{gha_utils-4.1.3 → gha_utils-4.2.0}/gha_utils/changelog.py

@@ -25,7 +25,7 @@ from textwrap import indent
 if sys.version_info >= (3, 11):
     import tomllib
 else:
-    import tomli as tomllib  # type: ignore[import]
+    import tomli as tomllib  # type: ignore[import-not-found]
 
 
 class Changelog:

{gha_utils-4.1.3 → gha_utils-4.2.0}/gha_utils/cli.py

@@ -56,13 +56,41 @@ 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 (
+def generate_header(ctx: Context) -> str:
+    """Generate metadata to be left as comments to the top of a file generated by
+    this CLI.
+    """
+    header = (
         f"# Generated by {ctx.command_path} v{__version__}"
         " - https://github.com/kdeldycke/workflows\n"
-        f"# Timestamp: {datetime.now().isoformat()}.\n\n"
+        f"# Timestamp: {datetime.now().isoformat()}\n"
     )
+    logging.debug(f"Generated header:\n{header}")
+    return header
+
+
+def remove_header(content: str) -> str:
+    """Return the same content provided, but without the blank lines and header metadata generated by the function above."""
+    logging.debug(f"Removing header from:\n{content}")
+    lines = []
+    still_in_header = True
+    for line in content.splitlines():
+        if still_in_header:
+            # We are still in the header as long as we have blank lines or we have
+            # comment lines matching the format produced by the method above.
+            if not line.strip() or line.startswith((
+                "# Generated by ",
+                "# Timestamp: ",
+            )):
+                continue
+            else:
+                still_in_header = False
+        # We are past the header, so keep all the lines: we have nothing left to remove.
+        lines.append(line)
+
+    headerless_content = "\n".join(lines)
+    logging.debug(f"Result of header removal:\n{headerless_content}")
+    return headerless_content
 
 
 @extra_group
@@ -95,10 +123,12 @@ 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`.
+    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.:
+    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"
     """
@@ -170,43 +200,76 @@ def changelog(ctx, source, changelog_path):
         f.write(content)
 
 
-@gha_utils.command(short_help="Sync Git's .mailmap at project's root")
+@gha_utils.command(short_help="Update Git's .mailmap file with missing contributors")
 @option(
     "--source",
-    type=path(exists=True, readable=True, resolve_path=True),
+    type=file_path(readable=True, resolve_path=True),
     default=".mailmap",
-    help=".mailmap source file to be updated with missing contributors.",
+    help="Mailmap source file to use as reference for contributors identities that "
+    "are already grouped.",
+)
+@option(
+    "--create-if-missing/--skip-if-missing",
+    is_flag=True,
+    default=True,
+    help="Create the destination mailmap file if it is not found. Or skip the update "
+    "process entirely if if does not already exists in the first place. This option "
+    f"is ignore if the destination is to print the result to {sys.stdout.name}.",
 )
 @argument(
-    "updated_mailmap",
+    "destination_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.
+def mailmap_sync(ctx, source, create_if_missing, destination_mailmap):
+    """Update a ``.mailmap`` file with all 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 -`.
+    By default the ``.mailmap`` at the root of the repository is read and its content
+    is reused as reference, so identities already aliased in there are preserved and
+    used as initial mapping. Only missing contributors not found in this initial mapping
+    are added.
 
-    To have the updated results written
-    to a file on disk, specify the output file like so: `gha-utils mailmap .mailmap`.
+    The resulting updated mapping is printed to the console output. So a bare call to
+    `gha-utils mailmap-sync` is the same as a call to
+    `gha-utils mailmap-sync --source .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(encoding="utf-8")
+    To have the updated mapping written to a file, specify the output file like so:
+    `gha-utils mailmap-sync .mailmap`.
 
-    mailmap = Mailmap(initial_content)
-    content = mailmap.updated_map()
+    The updated results are sorted. But no attempts are made at regrouping new
+    contributors. SO you have to edit entries by hand to regroup them
+    """
+    mailmap = Mailmap()
 
-    if is_stdout(updated_mailmap):
-        logging.info(f"Print updated results to {sys.stdout.name}")
+    if source.exists():
+        logging.info(f"Read initial mapping from {source}")
+        content = remove_header(source.read_text(encoding="utf-8"))
+        mailmap.parse(content)
+    else:
+        logging.debug(f"Mailmap source file {source} does not exists.")
+
+    mailmap.update_from_git()
+    new_content = mailmap.render()
+
+    if is_stdout(destination_mailmap):
+        logging.info(f"Print updated results to {sys.stdout.name}.")
+        logging.debug(
+            "Ignore the "
+            + ("--create-if-missing" if create_if_missing else "--skip-if-missing")
+            + " option."
+        )
     else:
-        logging.info(f"Save updated results to {updated_mailmap}")
+        logging.info(f"Save updated results to {destination_mailmap}")
+        if not create_if_missing and not destination_mailmap.exists():
+            logging.warning(
+                f"{destination_mailmap} does not exists, stop the sync process."
+            )
+            ctx.exit()
+        if content == new_content:
+            logging.warning("Nothing to update, stop the sync process.")
+            ctx.exit()
 
-    with file_writer(updated_mailmap) as f:
-        f.write(f"{get_header(ctx)}{content}")
+    with file_writer(destination_mailmap) as f:
+        f.write(generate_header(ctx) + new_content)

gha_utils-4.2.0/gha_utils/mailmap.py

@@ -0,0 +1,166 @@
+# 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 dataclasses import dataclass, field
+from functools import cached_property
+from subprocess import run
+
+from boltons.iterutils import unique  # type: ignore[import-untyped]
+
+
+@dataclass(order=True, frozen=True)
+class Record:
+    """A mailmap identity mapping entry."""
+
+    # Mapping is define as the first field so we have natural sorting,
+    # whatever the value of the pre_comment is.
+    canonical: str = ""
+    aliases: set[str] = field(default_factory=set)
+    pre_comment: str = ""
+
+    def __str__(self) -> str:
+        """Render the record with pre-comments first, followed by the identity mapping.
+
+        Sort all entries in the mapping without case-sensitivity, but keep the first in
+        its place as the canonical identity.
+        """
+        lines = []
+        if self.pre_comment:
+            lines.append(self.pre_comment)
+        if self.canonical:
+            lines.append(
+                " ".join((self.canonical, *sorted(self.aliases, key=str.casefold)))
+            )
+        return "\n".join(lines)
+
+
+class Mailmap:
+    """Helpers to manipulate ``.mailmap`` files.
+
+    ``.mailmap`` `file format is documented on Git website
+    <https://git-scm.com/docs/gitmailmap>`_.
+    """
+
+    records: list[Record] = list()
+
+    @staticmethod
+    def split_identities(mapping: str) -> tuple[str, set[str]]:
+        """Split a mapping of identities and normalize them."""
+        identities = []
+        for identity in map(str.strip, mapping.split(">")):
+            # Skip blank strings produced by uneven spaces.
+            if not identity:
+                continue
+            assert identity.count("<") == 1, f"Unexpected email format in {identity!r}"
+            name, email = identity.split("<", maxsplit=1)
+            identities.append(f"{name.strip()} <{email}>")
+
+        assert len(identities), f"No identities found in {mapping!r}"
+
+        identities = list(unique(identities))
+        return identities[0], set(identities[1:])
+
+    def parse(self, content: str) -> None:
+        """Parse mailmap content and add it to the current list of records.
+
+        Each non-empty, non-comment line is considered a mapping entry.
+
+        The preceding lines of a mapping entry are kept attached to it as pre-comments,
+        so the layout will be preserved on rendering, during which records are sorted.
+        """
+        logging.debug(f"Parsing:\n{content}")
+        pre_lines = []
+        for line in map(str.strip, content.splitlines()):
+            # Comment lines are added as-is.
+            if line.startswith("#"):
+                pre_lines.append(line)
+            # Blank lines are added as-is.
+            elif not line:
+                pre_lines.append(line)
+            # Mapping entry, which mark the end of a block, so add it to the list
+            # mailmap records.
+            else:
+                canonical, aliases = self.split_identities(line)
+                record = Record(
+                    pre_comment="\n".join(pre_lines),
+                    canonical=canonical,
+                    aliases=aliases,
+                )
+                logging.debug(record)
+                pre_lines = []
+                self.records.append(record)
+
+    def find(self, identity: str) -> bool:
+        """Returns ``True`` if the provided identity matched any record."""
+        identity_token = identity.lower()
+        for record in self.records:
+            # Identity matching is case insensitive:
+            # https://git-scm.com/docs/gitmailmap#_syntax
+            if identity_token in map(str.lower, (record.canonical, *record.aliases)):
+                return True
+        return False
+
+    @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 map(str.strip, process.stdout.splitlines()):
+            if line:
+                contributors.add(line)
+
+        logging.debug(
+            "Authors and committers found in Git history:\n"
+            + "\n".join(sorted(contributors, key=str.casefold))
+        )
+        return contributors
+
+    def update_from_git(self) -> None:
+        """Add to internal records all missing contributors found in commit history.
+
+        This method will refrain from adding contributors already registered as aliases.
+        """
+        for contributor in self.git_contributors:
+            if not self.find(contributor):
+                record = Record(canonical=contributor)
+                logging.info(f"Add new identity {record}")
+                self.records.append(record)
+            else:
+                logging.debug(f"Ignore existing identity {contributor}")
+
+    def render(self) -> str:
+        """Render internal records in Mailmap format."""
+        return "\n".join(
+            map(str, sorted(self.records, key=lambda r: r.canonical.casefold()))
+        )

{gha_utils-4.1.3 → gha_utils-4.2.0}/gha_utils/metadata.py

@@ -120,7 +120,7 @@ from bumpversion.config.files import find_config_file  # type: ignore[import-unt
 from bumpversion.show import resolve_name  # type: ignore[import-untyped]
 from packaging.specifiers import SpecifierSet
 from packaging.version import Version
-from pydriller import Commit, Git, Repository  # type: ignore[import]
+from pydriller import Commit, Git, Repository  # type: ignore[import-untyped]
 from pyproject_metadata import ConfigurationError, StandardMetadata
 from wcmatch.glob import (
     BRACE,
@@ -283,7 +283,7 @@ class Metadata:
         context = json.loads(os.environ["GITHUB_CONTEXT"])
         logging.debug("--- GitHub context ---")
         logging.debug(json.dumps(context, indent=4))
-        return context
+        return context  # type:ignore[no-any-return]
 
     def git_stash_count(self, git_repo: Git) -> int:
         """Returns the number of stashes."""
@@ -441,8 +441,8 @@ class Metadata:
             return None
 
         if bool(os.environ.get("GITHUB_BASE_REF")):
-            return WorkflowEvent.pull_request
-        return WorkflowEvent.push
+            return WorkflowEvent.pull_request  # type: ignore[no-any-return]
+        return WorkflowEvent.push  # type: ignore[no-any-return]
 
     @cached_property
     def commit_range(self) -> tuple[str, str] | None:
@@ -475,7 +475,7 @@ class Metadata:
         if not self.github_context or not self.event_type:
             return None
         # Pull request event.
-        if self.event_type in (
+        if self.event_type in (  # type: ignore[unreachable]
             WorkflowEvent.pull_request,
             WorkflowEvent.pull_request_target,
         ):
@@ -601,7 +601,7 @@ class Metadata:
 
     @property
     def is_python_project(self):
-        """Returns ``true`` if repository is a Python project.
+        """Returns ``True`` if repository is a Python project.
 
         Presence of a ``pyproject.toml`` file is not enough, as 3rd party tools can use
         that file to store their own configuration.
@@ -792,7 +792,7 @@ class Metadata:
         if self.new_commits_matrix:
             details = self.new_commits_matrix.get("include")
             if details:
-                version = details[0].get("current_version")  # type: ignore[union-attr]
+                version = details[0].get("current_version")
         return version
 
     @cached_property
@@ -805,18 +805,18 @@ class Metadata:
                 # This script is only designed for at most 1 release in the list of new
                 # commits.
                 assert len(details) == 1
-                version = details[0].get("current_version")  # type: ignore[union-attr]
+                version = details[0].get("current_version")
         return version
 
     @cached_property
     def is_sphinx(self) -> bool:
-        """Returns true if the Sphinx config file is present."""
+        """Returns ``True`` if the Sphinx config file is present."""
         # The Sphinx config file is present, that's enough for us.
         return self.sphinx_conf_path.exists() and self.sphinx_conf_path.is_file()
 
     @cached_property
     def active_autodoc(self) -> bool:
-        """Returns true if there are active Sphinx extensions."""
+        """Returns ``True`` if there are active Sphinx extensions."""
         if self.is_sphinx:
             # Look for list of active Sphinx extensions.
             for node in ast.parse(self.sphinx_conf_path.read_bytes()).body:

{gha_utils-4.1.3 → gha_utils-4.2.0}/gha_utils.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: gha-utils
-Version: 4.1.3
+Version: 4.2.0
 Summary: ⚙️ CLI helpers for GitHub Actions + reuseable workflows
 Author-email: Kevin Deldycke <kevin@deldycke.com>
 Project-URL: Homepage, https://github.com/kdeldycke/workflows
@@ -47,6 +47,7 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.8.6
 Description-Content-Type: text/markdown
 Requires-Dist: backports.strenum~=1.3.1; python_version < "3.11"
+Requires-Dist: boltons~=24.0.0
 Requires-Dist: bump-my-version~=0.24.0
 Requires-Dist: click-extra~=4.8.3
 Requires-Dist: packaging~=24.1

{gha_utils-4.1.3 → gha_utils-4.2.0}/gha_utils.egg-info/requires.txt

@@ -1,3 +1,4 @@
+boltons~=24.0.0
 bump-my-version~=0.24.0
 click-extra~=4.8.3
 packaging~=24.1

{gha_utils-4.1.3 → gha_utils-4.2.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 # Docs: https://packaging.python.org/en/latest/guides/writing-pyproject-toml/
 name = "gha-utils"
-version = "4.1.3"
+version = "4.2.0"
 # Python versions and their status: https://devguide.python.org/versions/
 # 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
@@ -72,6 +72,7 @@ classifiers = [
 ]
 dependencies = [
     "backports.strenum ~= 1.3.1 ; python_version < '3.11'",
+    "boltons ~= 24.0.0",
     "bump-my-version ~= 0.24.0",
     "click-extra ~= 4.8.3",
     "packaging ~= 24.1",
@@ -94,8 +95,16 @@ gha-utils = "gha_utils.__main__:main"
 [tool.setuptools.packages.find]
 include = ["gha_utils"]
 
+[tool.mypy]
+warn_unused_configs = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_return_any = true
+warn_unreachable = true
+pretty = true
+
 [tool.bumpversion]
-current_version = "4.1.3"
+current_version = "4.2.0"
 allow_dirty = true
 ignore_missing_files = true
 

gha_utils-4.1.3/gha_utils/mailmap.py

@@ -1,100 +0,0 @@
-# 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"
-            + "\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 (
-            "\n".join(header_comments)
-            + "\n\n"
-            + "\n".join(sorted(mappings, key=str.casefold))
-        )