gha-utils 4.1.4__py3-none-any.whl → 4.2.0__py3-none-any.whl

gha_utils/__init__.py

@@ -17,4 +17,4 @@
 
 from __future__ import annotations
 
-__version__ = "4.1.4"
+__version__ = "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/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/mailmap.py

@@ -18,37 +18,111 @@ from __future__ import annotations
 
 import logging
 import sys
+from dataclasses import dataclass, field
 from functools import cached_property
 from subprocess import run
-from textwrap import dedent
+
+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`` file.
+    """Helpers to manipulate ``.mailmap`` files.
 
-    The ``.mailmap`` files expected to be found in the root of repository.
+    ``.mailmap`` `file format is documented on Git website
+    <https://git-scm.com/docs/gitmailmap>`_.
     """
 
-    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}")
+    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.
+        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
@@ -62,8 +136,8 @@ class Mailmap:
         # Parse git CLI output.
         if process.returncode:
             sys.exit(process.stderr)
-        for line in process.stdout.splitlines():
-            if line.strip():
+        for line in map(str.strip, process.stdout.splitlines()):
+            if line:
                 contributors.add(line)
 
         logging.debug(
@@ -72,29 +146,21 @@ class Mailmap:
         )
         return contributors
 
-    def updated_map(self):
-        """Add all missing contributors from commit history to mailmap.
+    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.
         """
-        # 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))
+            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/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.4.dist-info → gha_utils-4.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: gha-utils
-Version: 4.1.4
+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
@@ -46,6 +46,7 @@ Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
 Requires-Python: >=3.8.6
 Description-Content-Type: text/markdown
+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.2.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+gha_utils/__init__.py,sha256=Tz40D2ZlD8ZokFTQ3MT6KpA0nZd0FTwFuwhnPcTKEY8,865
+gha_utils/__main__.py,sha256=Dck9BjpLXmIRS83k0mghAMcYVYiMiFLltQdfRuMSP_Q,1703
+gha_utils/changelog.py,sha256=EK0uz8IJidYrWoxoSWutoQ5_g3bdsGrKgOitVCiAXw4,5775
+gha_utils/cli.py,sha256=4wUG29fB0-Z-n105UBgIg5NLuqtODtoMLwKJP7RQFXo,9150
+gha_utils/mailmap.py,sha256=sum4XIme2Dis7XtHyO9U7ogWelZwqb-yvJ5I92PPnqg,6301
+gha_utils/metadata.py,sha256=cOVWY9Y9sCbR1QTUIjwej9y5KAMiw1pqiJAqAkH_3JI,47198
+gha_utils/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gha_utils-4.2.0.dist-info/METADATA,sha256=81DyHok5klvNfKCfJVNoKNgdmbvXoLcKwIgAc5NC-ic,17220
+gha_utils-4.2.0.dist-info/WHEEL,sha256=Z4pYXqR_rTB7OWNDYFOm1qRk0RX6GFP2o8LgvP453Hk,91
+gha_utils-4.2.0.dist-info/entry_points.txt,sha256=8bJOwQYf9ZqsLhBR6gUCzvwLNI9f8tiiBrJ3AR0EK4o,54
+gha_utils-4.2.0.dist-info/top_level.txt,sha256=C94Blb61YkkyPBwCdM3J_JPDjWH0lnKa5nGZeZ5M6yE,10
+gha_utils-4.2.0.dist-info/RECORD,,

{gha_utils-4.1.4.dist-info → gha_utils-4.2.0.dist-info}/WHEEL

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

gha_utils-4.1.4.dist-info/RECORD

@@ -1,12 +0,0 @@
-gha_utils/__init__.py,sha256=gDhYW8Bij0ynm3uEyK9IAiMLzNdlja2CmT4W15FjbRE,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=PkoEJvn9QnB0FdrIkYey___zPjogEPrsb67I1XRR08k,47117
-gha_utils/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-gha_utils-4.1.4.dist-info/METADATA,sha256=VAmzUvB9M3qYUL3uI6I4PZ_J5bp7Y6-iA9V25-9y5_0,17188
-gha_utils-4.1.4.dist-info/WHEEL,sha256=y4mX-SOX4fYIkonsAGA5N0Oy-8_gI4FXw5HNI1xqvWg,91
-gha_utils-4.1.4.dist-info/entry_points.txt,sha256=8bJOwQYf9ZqsLhBR6gUCzvwLNI9f8tiiBrJ3AR0EK4o,54
-gha_utils-4.1.4.dist-info/top_level.txt,sha256=C94Blb61YkkyPBwCdM3J_JPDjWH0lnKa5nGZeZ5M6yE,10
-gha_utils-4.1.4.dist-info/RECORD,,