python-semantic-release 10.2.0__tar.gz → 10.3.1__tar.gz

{python_semantic_release-10.2.0 → python_semantic_release-10.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-semantic-release
-Version: 10.2.0
+Version: 10.3.1
 Summary: Automatic Semantic Versioning for Python projects
 Author-email: Rolf Erik Lekang <me@rolflekang.com>
 License: MIT
@@ -88,5 +88,5 @@ The usage information and examples for this GitHub Action is available under
 the `GitHub Actions section`_ of `python-semantic-release.readthedocs.io`_.
 
 .. _python-semantic-release: https://pypi.org/project/python-semantic-release/
-.. _python-semantic-release.readthedocs.io: https://python-semantic-release.readthedocs.io/en/latest/
-.. _GitHub Actions section: https://python-semantic-release.readthedocs.io/en/latest/automatic-releases/github-actions.html
+.. _python-semantic-release.readthedocs.io: https://python-semantic-release.readthedocs.io/en/stable/
+.. _GitHub Actions section: https://python-semantic-release.readthedocs.io/en/stable/configuration/automatic-releases/github-actions.html

{python_semantic_release-10.2.0 → python_semantic_release-10.3.1}/README.rst

@@ -18,5 +18,5 @@ The usage information and examples for this GitHub Action is available under
 the `GitHub Actions section`_ of `python-semantic-release.readthedocs.io`_.
 
 .. _python-semantic-release: https://pypi.org/project/python-semantic-release/
-.. _python-semantic-release.readthedocs.io: https://python-semantic-release.readthedocs.io/en/latest/
-.. _GitHub Actions section: https://python-semantic-release.readthedocs.io/en/latest/automatic-releases/github-actions.html
+.. _python-semantic-release.readthedocs.io: https://python-semantic-release.readthedocs.io/en/stable/
+.. _GitHub Actions section: https://python-semantic-release.readthedocs.io/en/stable/configuration/automatic-releases/github-actions.html

{python_semantic_release-10.2.0 → python_semantic_release-10.3.1}/docs/concepts/getting_started.rst

@@ -215,7 +215,7 @@ To set commit exclusion patterns for a conventional commits parsers, add the fol
 
 .. code-block:: toml
 
-    [tool.semantic_release.changelog.exclude_commit_patterns]
+    [tool.semantic_release.changelog]
     # Recommended patterns for conventional commits parser that is scope aware
     exclude_commit_patterns = [
         '''chore(?:\([^)]*?\))?: .+''',

{python_semantic_release-10.2.0 → python_semantic_release-10.3.1}/docs/configuration/automatic-releases/github-actions.rst

@@ -19,6 +19,14 @@ There are two official GitHub Actions for Python Semantic Release:
     It is used to upload files, such as distribution artifacts and other assets,
     to a GitHub release.
 
+Included in this documentation are some recommended examples below if you want to get
+started quickly. These examples are not exhaustive and you will need to adjust them
+for your specific project needs especially if you are using a monorepo.
+
+- :ref:`GitHub Actions Example Workflows <gh_actions-examples>`
+
+- :ref:`GitHub Actions with Monorepos <gh_actions-monorepo>`
+
 .. note::
   These GitHub Actions are only simplified wrappers around the
   python-semantic-release CLI. Ultimately, they download and install the
@@ -513,6 +521,20 @@ and any actions that were taken.
 
 ----
 
+.. _gh_actions-psr-outputs-commit_sha:
+
+``commit_sha``
+""""""""""""""
+
+**Type:** ``string``
+
+The commit SHA of the release if a release was made, otherwise an empty string.
+
+Example upon release: ``d4c3b2a1e0f9c8b7a6e5d4c3b2a1e0f9c8b7a6e5``
+Example when no release was made: ``""``
+
+----
+
 .. _gh_actions-psr-outputs-is_prerelease:
 
 ``is_prerelease``
@@ -524,6 +546,32 @@ A boolean value indicating whether the released version is a prerelease.
 
 ----
 
+.. _gh_actions-psr-outputs-link:
+
+``link``
+""""""""
+
+**Type:** ``string``
+
+The URL link to the release if a release was made, otherwise an empty string.
+
+Example upon release: ``https://github.com/user/repo/releases/tag/v1.2.3``
+Example when no release was made: ``""``
+
+----
+
+.. _gh_actions-psr-outputs-previous_version:
+
+``previous_version``
+""""""""""""""""""""
+
+**Type:** ``string``
+
+The previous version before the release, if a release was or will be made. If no release is detected,
+this will be the current version or an empty string if no previous version exists.
+
+----
+
 .. _gh_actions-psr-outputs-released:
 
 ``released``
@@ -535,6 +583,18 @@ A boolean value indicating whether a release was made.
 
 ----
 
+.. _gh_actions-psr-outputs-release_notes:
+
+``release_notes``
+"""""""""""""""""""
+
+**Type:** ``string``
+
+The release notes generated by the release, if any. If no release was made,
+this will be an empty string.
+
+----
+
 .. _gh_actions-psr-outputs-version:
 
 ``version``
@@ -873,14 +933,14 @@ to the GitHub Release Assets as well.
           - name: Action | Semantic Version Release
             id: release
             # Adjust tag with desired version if applicable.
-            uses: python-semantic-release/python-semantic-release@v10.2.0
+            uses: python-semantic-release/python-semantic-release@v10.3.1
             with:
               github_token: ${{ secrets.GITHUB_TOKEN }}
               git_committer_name: "github-actions"
               git_committer_email: "actions@users.noreply.github.com"
 
           - name: Publish | Upload to GitHub Release Assets
-            uses: python-semantic-release/publish-action@v10.2.0
+            uses: python-semantic-release/publish-action@v10.3.1
             if: steps.release.outputs.released == 'true'
             with:
               github_token: ${{ secrets.GITHUB_TOKEN }}
@@ -979,7 +1039,7 @@ The equivalent GitHub Action configuration would be:
 
   - name: Action | Semantic Version Release
     # Adjust tag with desired version if applicable.
-    uses: python-semantic-release/python-semantic-release@v10.2.0
+    uses: python-semantic-release/python-semantic-release@v10.3.1
     with:
       github_token: ${{ secrets.GITHUB_TOKEN }}
       force: patch
@@ -1038,14 +1098,14 @@ Publish Action.
 
         - name: Release submodule 1
           id: release-submod-1
-          uses: python-semantic-release/python-semantic-release@v10.2.0
+          uses: python-semantic-release/python-semantic-release@v10.3.1
           with:
             directory: ${{ env.SUBMODULE_1_DIR }}
             github_token: ${{ secrets.GITHUB_TOKEN }}
 
         - name: Release submodule 2
           id: release-submod-2
-          uses: python-semantic-release/python-semantic-release@v10.2.0
+          uses: python-semantic-release/python-semantic-release@v10.3.1
           with:
             directory: ${{ env.SUBMODULE_2_DIR }}
             github_token: ${{ secrets.GITHUB_TOKEN }}
@@ -1057,7 +1117,7 @@ Publish Action.
         # ------------------------------------------------------------------- #
 
         - name: Publish | Upload package 1 to GitHub Release Assets
-          uses: python-semantic-release/publish-action@v10.2.0
+          uses: python-semantic-release/publish-action@v10.3.1
           if: steps.release-submod-1.outputs.released == 'true'
           with:
             directory: ${{ env.SUBMODULE_1_DIR }}
@@ -1065,7 +1125,7 @@ Publish Action.
             tag: ${{ steps.release-submod-1.outputs.tag }}
 
         - name: Publish | Upload package 2 to GitHub Release Assets
-          uses: python-semantic-release/publish-action@v10.2.0
+          uses: python-semantic-release/publish-action@v10.3.1
           if: steps.release-submod-2.outputs.released == 'true'
           with:
             directory: ${{ env.SUBMODULE_2_DIR }}

{python_semantic_release-10.2.0 → python_semantic_release-10.3.1}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-semantic-release"
-version = "10.2.0"
+version = "10.3.1"
 description = "Automatic Semantic Versioning for Python projects"
 requires-python = ">=3.8"
 license = { text = "MIT" }

{python_semantic_release-10.2.0 → python_semantic_release-10.3.1}/src/semantic_release/cli/commands/version.py

@@ -18,7 +18,10 @@ from semantic_release.cli.changelog_writer import (
     generate_release_notes,
     write_changelog_files,
 )
-from semantic_release.cli.github_actions_output import VersionGitHubActionsOutput
+from semantic_release.cli.github_actions_output import (
+    PersistenceMode,
+    VersionGitHubActionsOutput,
+)
 from semantic_release.cli.util import noop_report, rprint
 from semantic_release.const import DEFAULT_SHELL, DEFAULT_VERSION
 from semantic_release.enums import LevelBump
@@ -30,6 +33,7 @@ from semantic_release.errors import (
 )
 from semantic_release.gitproject import GitProject
 from semantic_release.globals import logger
+from semantic_release.hvcs.github import Github
 from semantic_release.hvcs.remote_hvcs_base import RemoteHvcsBase
 from semantic_release.version.algorithm import (
     next_version,
@@ -466,7 +470,19 @@ def version(  # noqa: C901
     major_on_zero = runtime.major_on_zero
     no_verify = runtime.no_git_verify
     opts = runtime.global_cli_options
-    gha_output = VersionGitHubActionsOutput(released=False)
+    gha_output = VersionGitHubActionsOutput(
+        gh_client=(
+            hvcs_client
+            if isinstance(hvcs_client, Github)
+            else Github(hvcs_client.remote_url(use_token=False))
+        ),
+        mode=(
+            PersistenceMode.TEMPORARY
+            if opts.noop or (not commit_changes and not create_tag)
+            else PersistenceMode.PERMANENT
+        ),
+        released=False,
+    )
 
     forced_level_bump = None if not force_level else LevelBump.from_string(force_level)
     prerelease = is_forced_prerelease(
@@ -572,6 +588,12 @@ def version(  # noqa: C901
     if print_only or print_only_tag:
         return
 
+    # TODO: need a better way as this is inconsistent if releasing older version patches
+    if last_release := last_released(config.repo_dir, tag_format=config.tag_format):
+        # If we have a last release, we can set the previous version for the
+        # GitHub Actions output
+        gha_output.prev_version = last_release[1]
+
     with Repo(str(runtime.repo_dir)) as git_repo:
         release_history = ReleaseHistory.from_git_history(
             repo=git_repo,
@@ -641,6 +663,29 @@ def version(  # noqa: C901
             click.echo("Build failed, aborting release", err=True)
             ctx.exit(1)
 
+    license_cfg = runtime.project_metadata.get(
+        "license-expression",
+        runtime.project_metadata.get(
+            "license",
+            "",
+        ),
+    )
+
+    license_cfg = "" if not isinstance(license_cfg, (str, dict)) else license_cfg
+    license_cfg = (
+        license_cfg.get("text", "") if isinstance(license_cfg, dict) else license_cfg
+    )
+
+    gha_output.release_notes = release_notes = generate_release_notes(
+        hvcs_client,
+        release=release_history.released[new_version],
+        template_dir=runtime.template_dir,
+        history=release_history,
+        style=runtime.changelog_style,
+        mask_initial_release=runtime.changelog_mask_initial_release,
+        license_name="" if not isinstance(license_cfg, str) else license_cfg,
+    )
+
     project = GitProject(
         directory=runtime.repo_dir,
         commit_author=runtime.commit_author,
@@ -676,6 +721,9 @@ def version(  # noqa: C901
             noop=opts.noop,
         )
 
+        with Repo(str(runtime.repo_dir)) as git_repo:
+            gha_output.commit_sha = git_repo.head.commit.hexsha
+
     if push_changes:
         remote_url = runtime.hvcs_client.remote_url(
             use_token=not runtime.ignore_token_for_push
@@ -710,33 +758,6 @@ def version(  # noqa: C901
         logger.info("Remote does not support releases. Skipping release creation...")
         return
 
-    license_cfg = runtime.project_metadata.get(
-        "license-expression",
-        runtime.project_metadata.get(
-            "license",
-            "",
-        ),
-    )
-
-    if not isinstance(license_cfg, (str, dict)) or license_cfg is None:
-        license_cfg = ""
-
-    license_name = (
-        license_cfg.get("text", "")
-        if isinstance(license_cfg, dict)
-        else license_cfg or ""
-    )
-
-    release_notes = generate_release_notes(
-        hvcs_client,
-        release=release_history.released[new_version],
-        template_dir=runtime.template_dir,
-        history=release_history,
-        style=runtime.changelog_style,
-        mask_initial_release=runtime.changelog_mask_initial_release,
-        license_name=license_name,
-    )
-
     exception: Exception | None = None
     help_message = ""
     try:

python_semantic_release-10.3.1/src/semantic_release/cli/github_actions_output.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+import os
+from enum import Enum
+from re import compile as regexp
+from typing import TYPE_CHECKING
+
+from semantic_release.globals import logger
+from semantic_release.version.version import Version
+
+if TYPE_CHECKING:
+    from typing import Any
+
+    from semantic_release.hvcs.github import Github
+
+
+class PersistenceMode(Enum):
+    TEMPORARY = "temporary"
+    PERMANENT = "permanent"
+
+
+class VersionGitHubActionsOutput:
+    OUTPUT_ENV_VAR = "GITHUB_OUTPUT"
+
+    def __init__(
+        self,
+        gh_client: Github,
+        mode: PersistenceMode = PersistenceMode.PERMANENT,
+        released: bool | None = None,
+        version: Version | None = None,
+        commit_sha: str | None = None,
+        release_notes: str | None = None,
+        prev_version: Version | None = None,
+    ) -> None:
+        self._gh_client = gh_client
+        self._mode = mode
+        self._released = released
+        self._version = version
+        self._commit_sha = commit_sha
+        self._release_notes = release_notes
+        self._prev_version = prev_version
+
+    @property
+    def released(self) -> bool | None:
+        return self._released
+
+    @released.setter
+    def released(self, value: bool) -> None:
+        if not isinstance(value, bool):
+            raise TypeError("output 'released' is boolean")
+        self._released = value
+
+    @property
+    def version(self) -> Version | None:
+        return self._version if self._version is not None else None
+
+    @version.setter
+    def version(self, value: Version) -> None:
+        if not isinstance(value, Version):
+            raise TypeError("output 'released' should be a Version")
+        self._version = value
+
+    @property
+    def tag(self) -> str | None:
+        return self.version.as_tag() if self.version is not None else None
+
+    @property
+    def is_prerelease(self) -> bool | None:
+        return self.version.is_prerelease if self.version is not None else None
+
+    @property
+    def commit_sha(self) -> str | None:
+        return self._commit_sha if self._commit_sha else None
+
+    @commit_sha.setter
+    def commit_sha(self, value: str) -> None:
+        if not isinstance(value, str):
+            raise TypeError("output 'commit_sha' should be a string")
+
+        if not regexp(r"^[0-9a-f]{40}$").match(value):
+            raise ValueError(
+                "output 'commit_sha' should be a valid 40-hex-character SHA"
+            )
+
+        self._commit_sha = value
+
+    @property
+    def release_notes(self) -> str | None:
+        return self._release_notes if self._release_notes else None
+
+    @release_notes.setter
+    def release_notes(self, value: str) -> None:
+        if not isinstance(value, str):
+            raise TypeError("output 'release_notes' should be a string")
+        self._release_notes = value
+
+    @property
+    def prev_version(self) -> Version | None:
+        if not self.released:
+            return self.version
+        return self._prev_version if self._prev_version else None
+
+    @prev_version.setter
+    def prev_version(self, value: Version) -> None:
+        if not isinstance(value, Version):
+            raise TypeError("output 'prev_version' should be a Version")
+        self._prev_version = value
+
+    def to_output_text(self) -> str:
+        missing: set[str] = set()
+        if self.version is None:
+            missing.add("version")
+        if self.released is None:
+            missing.add("released")
+        if self.released:
+            if self.release_notes is None:
+                missing.add("release_notes")
+            if self._mode is PersistenceMode.PERMANENT and self.commit_sha is None:
+                missing.add("commit_sha")
+
+        if missing:
+            raise ValueError(
+                f"some required outputs were not set: {', '.join(missing)}"
+            )
+
+        output_values: dict[str, Any] = {
+            "released": str(self.released).lower(),
+            "version": str(self.version),
+            "tag": self.tag,
+            "is_prerelease": str(self.is_prerelease).lower(),
+            "link": self._gh_client.create_release_url(self.tag) if self.tag else "",
+            "previous_version": str(self.prev_version) if self.prev_version else "",
+            "commit_sha": self.commit_sha if self.commit_sha else "",
+        }
+
+        multiline_output_values: dict[str, str] = {
+            "release_notes": self.release_notes if self.release_notes else "",
+        }
+
+        output_lines = [
+            *[f"{key}={value!s}{os.linesep}" for key, value in output_values.items()],
+            *[
+                f"{key}<<EOF{os.linesep}{value}EOF{os.linesep}"
+                if value
+                else f"{key}={os.linesep}"
+                for key, value in multiline_output_values.items()
+            ],
+        ]
+
+        return str.join("", output_lines)
+
+    def write_if_possible(self, filename: str | None = None) -> None:
+        output_file = filename or os.getenv(self.OUTPUT_ENV_VAR)
+        if not output_file:
+            logger.info("not writing GitHub Actions output, as no file specified")
+            return
+
+        with open(output_file, "ab") as f:
+            f.write(self.to_output_text().encode("utf-8"))

{python_semantic_release-10.2.0 → python_semantic_release-10.3.1}/src/semantic_release/cli/util.py

@@ -9,6 +9,7 @@ from textwrap import dedent, indent
 from typing import Any
 
 import rich
+import rich.markup
 import tomlkit
 from tomlkit.exceptions import TOMLKitError
 
@@ -26,8 +27,7 @@ def noop_report(msg: str) -> None:
     Rich-prints a msg with a standard prefix to report when an action is not being
     taken due to a "noop" flag
     """
-    fullmsg = "[bold cyan][:shield: NOP] " + msg
-    rprint(fullmsg)
+    rprint(f"[bold cyan][:shield: NOP] {rich.markup.escape(msg)}")
 
 
 def indented(msg: str, prefix: str = " " * 4) -> str:

python_semantic_release-10.3.1/tests/e2e/cmd_version/test_version_github_actions.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+import os
+from datetime import timezone
+from typing import TYPE_CHECKING, cast
+
+import pytest
+from freezegun import freeze_time
+from pytest_lazy_fixtures.lazy_fixture import lf as lazy_fixture
+
+from semantic_release.version.version import Version
+
+from tests.const import EXAMPLE_PROJECT_LICENSE, MAIN_PROG_NAME, VERSION_SUBCMD
+from tests.fixtures.repos import (
+    repo_w_git_flow_w_alpha_prereleases_n_conventional_commits,
+)
+from tests.util import actions_output_to_dict, assert_successful_exit_code
+
+if TYPE_CHECKING:
+    from semantic_release.hvcs.github import Github
+
+    from tests.conftest import GetStableDateNowFn, RunCliFn
+    from tests.fixtures.example_project import ExProjectDir
+    from tests.fixtures.git_repo import (
+        BuiltRepoResult,
+        GenerateDefaultReleaseNotesFromDefFn,
+        GetCfgValueFromDefFn,
+        GetHvcsClientFromRepoDefFn,
+        GetVersionsFromRepoBuildDefFn,
+        SplitRepoActionsByReleaseTagsFn,
+    )
+
+
+@pytest.mark.parametrize(
+    "repo_result",
+    [lazy_fixture(repo_w_git_flow_w_alpha_prereleases_n_conventional_commits.__name__)],
+)
+def test_version_writes_github_actions_output(
+    repo_result: BuiltRepoResult,
+    run_cli: RunCliFn,
+    example_project_dir: ExProjectDir,
+    get_cfg_value_from_def: GetCfgValueFromDefFn,
+    get_hvcs_client_from_repo_def: GetHvcsClientFromRepoDefFn,
+    generate_default_release_notes_from_def: GenerateDefaultReleaseNotesFromDefFn,
+    split_repo_actions_by_release_tags: SplitRepoActionsByReleaseTagsFn,
+    get_versions_from_repo_build_def: GetVersionsFromRepoBuildDefFn,
+    stable_now_date: GetStableDateNowFn,
+):
+    mock_output_file = example_project_dir / "action.out"
+    repo_def = repo_result["definition"]
+    tag_format_str = cast(str, get_cfg_value_from_def(repo_def, "tag_format_str"))
+    all_versions = get_versions_from_repo_build_def(repo_def)
+    latest_release_version = all_versions[-1]
+    release_tag = tag_format_str.format(version=latest_release_version)
+    previous_version = (
+        Version.parse(all_versions[-2]) if len(all_versions) > 1 else None
+    )
+    hvcs_client = cast("Github", get_hvcs_client_from_repo_def(repo_def))
+    repo_actions_per_version = split_repo_actions_by_release_tags(
+        repo_definition=repo_def,
+        tag_format_str=tag_format_str,
+    )
+    expected_gha_output = {
+        "released": str(True).lower(),
+        "version": latest_release_version,
+        "tag": release_tag,
+        "link": hvcs_client.create_release_url(release_tag),
+        "commit_sha": "0" * 40,
+        "is_prerelease": str(
+            Version.parse(latest_release_version).is_prerelease
+        ).lower(),
+        "previous_version": str(previous_version) if previous_version else "",
+        "release_notes": generate_default_release_notes_from_def(
+            version_actions=repo_actions_per_version[release_tag],
+            hvcs=hvcs_client,
+            previous_version=previous_version,
+            license_name=EXAMPLE_PROJECT_LICENSE,
+            mask_initial_release=get_cfg_value_from_def(
+                repo_def, "mask_initial_release"
+            ),
+        ),
+    }
+
+    # Remove the previous tag & version commit
+    repo_result["repo"].git.tag(release_tag, delete=True)
+    repo_result["repo"].git.reset("HEAD~1", hard=True)
+
+    # Act
+    with freeze_time(stable_now_date().astimezone(timezone.utc)):
+        cli_cmd = [MAIN_PROG_NAME, VERSION_SUBCMD, "--no-push"]
+        result = run_cli(
+            cli_cmd[1:], env={"GITHUB_OUTPUT": str(mock_output_file.resolve())}
+        )
+
+    assert_successful_exit_code(result, cli_cmd)
+
+    # Update the expected output with the commit SHA
+    expected_gha_output["commit_sha"] = repo_result["repo"].head.commit.hexsha
+
+    if not mock_output_file.exists():
+        pytest.fail(
+            f"Expected output file {mock_output_file} to be created, but it does not exist."
+        )
+
+    # Extract the output
+    with open(mock_output_file, encoding="utf-8", newline=os.linesep) as rfd:
+        action_outputs = actions_output_to_dict(rfd.read())
+
+    # Evaluate
+    expected_keys = set(expected_gha_output.keys())
+    actual_keys = set(action_outputs.keys())
+    key_difference = expected_keys.symmetric_difference(actual_keys)
+
+    assert not key_difference, f"Unexpected keys found: {key_difference}"
+
+    assert expected_gha_output["released"] == action_outputs["released"]
+    assert expected_gha_output["version"] == action_outputs["version"]
+    assert expected_gha_output["tag"] == action_outputs["tag"]
+    assert expected_gha_output["is_prerelease"] == action_outputs["is_prerelease"]
+    assert expected_gha_output["link"] == action_outputs["link"]
+    assert expected_gha_output["previous_version"] == action_outputs["previous_version"]
+    assert expected_gha_output["commit_sha"] == action_outputs["commit_sha"]
+    assert expected_gha_output["release_notes"] == action_outputs["release_notes"]