python-semantic-release · codejedi365 · Jan 28, 2025 · Jan 28, 2025 · Jan 28, 2025 · Dec 24, 2024
diff --git a/config/release-templates/.release_notes.md.j2 b/config/release-templates/.release_notes.md.j2
@@ -94,11 +94,7 @@
 {{
  "- %s" | format(
    format_link(
-      [
-        "https://pypi.org/project",
-        repo_name,
-        release.version | string,
-      ] | join("/"),
+      repo_name | create_pypi_url(release.version | string),
      "PyPi Registry",
    )
  )

diff --git a/docs/changelog_templates.rst b/docs/changelog_templates.rst
@@ -658,6 +658,27 @@ The filters provided vary based on the VCS configured and available features:
          )
      }}

+* ``create_pypi_url(package_name: str, version: str = "")``: given a package name and an optional
+  version, return a URL to the PyPI page for the package. If a version is provided, the URL will
+  point to the specific version page. If no version is provided, the URL will point to the package
+  page.
+
+  *Introduced in ${NEW_RELEASE_TAG}.*
+
+  **Example Usage:**
+
+  .. code:: jinja
+
+      {{ "example-package" | create_pypi_url }}
+      {{ "example-package" | create_pypi_url("1.0.0") }}
+
+  **Markdown Output:**
+
+  .. code:: markdown
+
+      https://pypi.org/project/example-package
+      https://pypi.org/project/example-package/1.0.0
+
 * ``create_server_url (Callable[[PathStr, AuthStr | None, QueryStr | None, FragmentStr | None], UrlStr])``:
  when given a path, prepend the configured vcs server host and url scheme.  Optionally you
  can provide, a auth string, a query string or a url fragment to be normalized into the

diff --git a/src/semantic_release/changelog/context.py b/src/semantic_release/changelog/context.py
@@ -4,10 +4,13 @@
 import os
 from dataclasses import dataclass
 from enum import Enum
-from pathlib import Path
+from pathlib import Path, PurePosixPath
 from re import compile as regexp
 from typing import TYPE_CHECKING, Any, Callable, Literal

+from urllib3.util import Url
+
+from semantic_release.const import PYPI_WEB_DOMAIN
 from semantic_release.helpers import sort_numerically

 if TYPE_CHECKING:  # pragma: no cover
@@ -86,6 +89,7 @@ def make_changelog_context(
        hvcs_type=hvcs_client.__class__.__name__.lower(),
        filters=(
            *hvcs_client.get_changelog_context_filters(),
+            create_pypi_url,
            read_file,
            convert_md_to_rst,
            autofit_text_width,
@@ -94,6 +98,17 @@ def make_changelog_context(
    )


+def create_pypi_url(package_name: str, version: str = "") -> str:
+    project_name = package_name.strip("/").strip()
+    if not project_name:
+        raise ValueError("package_name must not be empty!")
+    return Url(
+        scheme="https",
+        host=PYPI_WEB_DOMAIN,
+        path=str(PurePosixPath("project", project_name, version.strip("/").strip())),
+    ).url.rstrip("/")
+
+
 def read_file(filepath: str) -> str:
    try:
        if not filepath:

diff --git a/src/semantic_release/cli/changelog_writer.py b/src/semantic_release/cli/changelog_writer.py
@@ -13,6 +13,7 @@
 from semantic_release.changelog.context import (
    ReleaseNotesContext,
    autofit_text_width,
+    create_pypi_url,
    make_changelog_context,
 )
 from semantic_release.changelog.template import environment, recursive_render
@@ -257,6 +258,7 @@ def generate_release_notes(
        mask_initial_release=mask_initial_release,
        filters=(
            *hvcs_client.get_changelog_context_filters(),
+            create_pypi_url,
            autofit_text_width,
            sort_numerically,
        ),

diff --git a/src/semantic_release/const.py b/src/semantic_release/const.py
@@ -3,6 +3,8 @@
 import os
 import re

+PYPI_WEB_DOMAIN = "pypi.org"
+
 # https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string
 SEMVER_REGEX = re.compile(
    r"""

diff --git a/tests/unit/semantic_release/changelog/test_changelog_context.py b/tests/unit/semantic_release/changelog/test_changelog_context.py
@@ -585,3 +585,77 @@ def test_changelog_context_sort_numerically_reverse(

    # Evaluate
    assert expected_changelog == actual_changelog
+
+
+def test_changelog_context_pypi_url_filter(
+    example_git_https_url: str,
+    artificial_release_history: ReleaseHistory,
+    changelog_md_file: Path,
+):
+    changelog_tpl = dedent(
+        """\
+        {{ "example-package" | create_pypi_url }}
+        """
+    )
+
+    expected_changelog = dedent(
+        """\
+        https://pypi.org/project/example-package
+        """
+    )
+
+    env = environment(trim_blocks=True, lstrip_blocks=True, keep_trailing_newline=True)
+    context = make_changelog_context(
+        hvcs_client=Gitlab(example_git_https_url),
+        release_history=artificial_release_history,
+        mode=ChangelogMode.UPDATE,
+        prev_changelog_file=changelog_md_file,
+        insertion_flag="",
+        mask_initial_release=False,
+    )
+    context.bind_to_environment(env)
+
+    # Create changelog from template with environment
+    actual_changelog = env.from_string(changelog_tpl).render()
+
+    # Evaluate
+    assert expected_changelog == actual_changelog
+
+
+def test_changelog_context_pypi_url_filter_tagged(
+    example_git_https_url: str,
+    artificial_release_history: ReleaseHistory,
+    changelog_md_file: Path,
+):
+    version = "1.0.0"
+    changelog_tpl = dedent(
+        """\
+        {%    set release = context.history.released.values() | first
+        %}{{
+              "example-package" | create_pypi_url(release.version | string)
+        }}
+        """
+    )
+
+    expected_changelog = dedent(
+        f"""\
+        https://pypi.org/project/example-package/{version}
+        """
+    )
+
+    env = environment(trim_blocks=True, lstrip_blocks=True, keep_trailing_newline=True)
+    context = make_changelog_context(
+        hvcs_client=Gitlab(example_git_https_url),
+        release_history=artificial_release_history,
+        mode=ChangelogMode.UPDATE,
+        prev_changelog_file=changelog_md_file,
+        insertion_flag="",
+        mask_initial_release=False,
+    )
+    context.bind_to_environment(env)
+
+    # Create changelog from template with environment
+    actual_changelog = env.from_string(changelog_tpl).render()
+
+    # Evaluate
+    assert expected_changelog == actual_changelog
diff --git a/tests/unit/semantic_release/changelog/test_release_notes.py b/tests/unit/semantic_release/changelog/test_release_notes.py
@@ -547,3 +547,57 @@ def test_release_notes_context_sort_numerically_filter_reversed(
    )

    assert expected_content == actual_content
+
+
+def test_release_notes_context_pypi_url_filter(
+    example_git_https_url: str,
+    single_release_history: ReleaseHistory,
+    example_project_dir: ExProjectDir,
+    change_to_ex_proj_dir: None,
+):
+    version = list(single_release_history.released.keys())[-1]
+    release = single_release_history.released[version]
+
+    example_project_dir.joinpath(".release_notes.md.j2").write_text(
+        """{{ "example-package" | create_pypi_url }}"""
+    )
+
+    expected_content = f"https://pypi.org/project/example-package{os.linesep}"
+
+    actual_content = generate_release_notes(
+        hvcs_client=Github(remote_url=example_git_https_url),
+        release=release,
+        template_dir=example_project_dir,
+        history=single_release_history,
+        style="angular",
+        mask_initial_release=False,
+    )
+
+    assert expected_content == actual_content
+
+
+def test_release_notes_context_pypi_url_filter_tagged(
+    example_git_https_url: str,
+    single_release_history: ReleaseHistory,
+    example_project_dir: ExProjectDir,
+    change_to_ex_proj_dir: None,
+):
+    version = list(single_release_history.released.keys())[-1]
+    release = single_release_history.released[version]
+
+    example_project_dir.joinpath(".release_notes.md.j2").write_text(
+        """{{ "example-package" | create_pypi_url(release.version | string) }}"""
+    )
+
+    expected_content = f"https://pypi.org/project/example-package/{version}{os.linesep}"
+
+    actual_content = generate_release_notes(
+        hvcs_client=Github(remote_url=example_git_https_url),
+        release=release,
+        template_dir=example_project_dir,
+        history=single_release_history,
+        style="angular",
+        mask_initial_release=False,
+    )
+
+    assert expected_content == actual_content