Merge branch 'pantsbuild:main' into main

Author: github-actions[bot]

build-support/bin/external_tool/helm.py

@@ -0,0 +1,26 @@
+# Copyright 2026 Pants project contributors (see CONTRIBUTORS.md).
+# Licensed under the Apache License, Version 2.0 (see LICENSE).
+from collections.abc import Iterator
+
+from external_tool.github import GithubReleases
+
+
+class HelmReleases:
+    """Fetches Helm releases from GitHub.
+
+    Helm binaries are hosted on get.helm.sh, but releases are published on
+    GitHub (helm/helm). This class uses the GitHub Releases API to discover
+    available versions.
+
+    See https://github.com/helm/helm/issues/5663 for historical hosting discussion.
+    """
+
+    _GITHUB_URL_TEMPLATE = "https://github.com/helm/helm/releases/download/v{version}/helm-v{version}-{platform}.tar.gz"
+
+    def __init__(self, only_latest: bool) -> None:
+        self.only_latest = only_latest
+        self._github_releases = GithubReleases(only_latest=only_latest)
+
+    def get_releases(self, url_template: str) -> Iterator[str]:
+        # Ignore the url_template (which points to get.helm.sh) and use GitHub instead
+        return self._github_releases.get_releases(self._GITHUB_URL_TEMPLATE)

build-support/bin/external_tool/helm_test.py

@@ -0,0 +1,57 @@
+# Copyright 2026 Pants project contributors (see CONTRIBUTORS.md).
+# Licensed under the Apache License, Version 2.0 (see LICENSE).
+from external_tool.helm import HelmReleases
+
+
+def test_helm_releases_only_latest(monkeypatch) -> None:
+    mock_releases = [
+        {"tag_name": "v3.14.3"},
+        {"tag_name": "v3.14.2"},
+        {"tag_name": "v3.13.0"},
+    ]
+
+    def mock_fetch(url: str):
+        assert "helm/helm" in url
+        return mock_releases
+
+    monkeypatch.setattr("external_tool.github.fetch_releases", mock_fetch)
+
+    helm = HelmReleases(only_latest=True)
+    versions = list(helm.get_releases("https://get.helm.sh/helm-v{version}-{platform}.tar.gz"))
+
+    assert versions == ["3.14.3"]
+
+
+def test_helm_releases_all_versions(monkeypatch) -> None:
+    mock_releases = [
+        {"tag_name": "v3.14.3"},
+        {"tag_name": "v3.14.2"},
+        {"tag_name": "v3.13.0"},
+    ]
+
+    def mock_fetch(url: str):
+        assert "helm/helm" in url
+        return mock_releases
+
+    monkeypatch.setattr("external_tool.github.fetch_releases", mock_fetch)
+
+    helm = HelmReleases(only_latest=False)
+    versions = list(helm.get_releases("https://get.helm.sh/helm-v{version}-{platform}.tar.gz"))
+
+    assert versions == ["3.14.3", "3.14.2", "3.13.0"]
+
+
+def test_helm_releases_uses_github_api(monkeypatch) -> None:
+    captured_url = None
+
+    def mock_fetch(url: str):
+        nonlocal captured_url
+        captured_url = url
+        return [{"tag_name": "v3.14.3"}]
+
+    monkeypatch.setattr("external_tool.github.fetch_releases", mock_fetch)
+
+    helm = HelmReleases(only_latest=True)
+    list(helm.get_releases("https://get.helm.sh/helm-v{version}-{platform}.tar.gz"))
+
+    assert captured_url == "https://api.github.com/repos/helm/helm/releases"

build-support/bin/external_tool_upgrade.py

@@ -27,12 +27,14 @@
 
 import requests
 from external_tool.github import GithubReleases
+from external_tool.helm import HelmReleases
 from external_tool.kubectl import KubernetesReleases
 from external_tool.python import (
     find_modules_with_subclasses,
     get_class_variables,
     replace_class_variables,
 )
+from packaging.specifiers import InvalidSpecifier, SpecifierSet
 from packaging.version import Version
 from tqdm import tqdm
 
@@ -148,6 +150,7 @@ def fetch_version(
 class Tool:
     default_known_versions: list[str]
     default_url_template: str
+    default_version: str
     default_url_platform_mapping: dict[str, str] | None = None
 
 
@@ -156,6 +159,22 @@ class Mode(StrEnum):
     calculate_sha_and_size = "calculate-sha-and-size"
 
 
+def filter_versions_by_constraint(
+    versions: list[ExternalToolVersion],
+    constraint: str | None,
+) -> list[ExternalToolVersion]:
+    """Filter versions using packaging.specifiers.
+
+    >>> filter_versions_by_constraint([ExternalToolVersion("5.0", "cowsay", "", 0)], ">=4.0,<6.0")
+    [ExternalToolVersion(version='5.0', platform='cowsay', sha256='', filesize=0, url_override=None)]
+    """
+    if constraint is None:
+        return versions
+
+    specifier = SpecifierSet(constraint)
+    return [v for v in versions if specifier.contains(v.version.lstrip("v"))]
+
+
 EXCLUDE_TOOLS = {
     "ExternalCCSubsystem",  # Doesn't define default_url_template.
     "ExternalHelmPlugin",  # Is a base class itself.
@@ -202,9 +221,26 @@ def main():
         type=Mode,
         default="calculate-sha-and-size",
     )
+    parser.add_argument(
+        "--version-constraint",
+        default=None,
+        help="Version constraint to filter versions (e.g., '>2.2.2,<3')",
+    )
+    parser.add_argument(
+        "--max-releases",
+        type=int,
+        default=64,
+        help="Maximum number of releases to fetch when --version-constraint is set (default: 64)",
+    )
 
     args = parser.parse_args()
 
+    if args.version_constraint:
+        try:
+            SpecifierSet(args.version_constraint)
+        except InvalidSpecifier as e:
+            parser.error(f"Invalid version constraint: {e}")
+
     level = logging.DEBUG if args.verbose else logging.INFO
     logging.basicConfig(level=logging.INFO, format="%(message)s")
     logging.getLogger(__name__).level = level
@@ -227,12 +263,15 @@ def main():
     pool = ThreadPool(processes=args.workers)
     platforms = args.platforms.split(",")
 
+    # When a version constraint is specified, fetch more releases (up to --max-releases) to filter
+    only_latest = args.version_constraint is None
+
     mapping: dict[str, Releases | None] = {
         "dl.k8s.io": KubernetesReleases(pool=pool, only_latest=True),
         "github.com": GithubReleases(only_latest=True),
+        "get.helm.sh": HelmReleases(only_latest=only_latest),
         "releases.hashicorp.com": None,  # TODO
         "raw.githubusercontent.com": None,  # TODO
-        "get.helm.sh": None,  # TODO
         "binaries.pantsbuild.org": None,  # TODO
     }
 
@@ -254,6 +293,20 @@ def main():
             continue
 
         releases = list(releases.get_releases(tool.default_url_template))
+
+        # Limit and filter releases by constraint before downloading binaries
+        if args.version_constraint:
+            releases = releases[: args.max_releases]
+            specifier = SpecifierSet(args.version_constraint)
+            releases = [v for v in releases if specifier.contains(v.lstrip("v"))]
+            if not releases:
+                logger.warning(
+                    "No releases for %s match constraint %r, skipping",
+                    class_name,
+                    args.version_constraint,
+                )
+                continue
+
         for version in releases:
             for platform in platforms:
                 futures.append(
@@ -285,18 +338,46 @@ def main():
         existing_versions = {
             ExternalToolVersion.decode(version) for version in tool.default_known_versions
         }
-        fetched_versions = {version.version for version in versions}
+
+        path, class_name = group
+
+        external_versions = [v.version for v in versions]
+        if args.version_constraint:
+            external_versions = filter_versions_by_constraint(
+                external_versions, args.version_constraint
+            )
+            if not external_versions:
+                logger.warning(
+                    "No fetched versions for %s match constraint %r, skipping",
+                    class_name,
+                    args.version_constraint,
+                )
+                continue
+
+        fetched_versions = set(external_versions)
 
         known_versions = list(existing_versions | fetched_versions)
         known_versions.sort(key=lambda tu: (Version(tu.version), tu.platform), reverse=True)
 
-        path, class_name = group
+        if args.version_constraint:
+            # Only upgrade if the newest matching version is greater than current default
+            filtered_versions = filter_versions_by_constraint(
+                known_versions, args.version_constraint
+            )
+            current_default = Version(tool.default_version.lstrip("v"))
+            newest_matching = Version(filtered_versions[0].version.lstrip("v"))
+            if newest_matching > current_default:
+                default_version = filtered_versions[0].version
+            else:
+                default_version = tool.default_version
+        else:
+            default_version = known_versions[0].version
 
         replace_class_variables(
             path,
             class_name,
             replacements={
-                "default_version": known_versions[0].version,
+                "default_version": default_version,
                 "default_known_versions": [v.encode() for v in known_versions],
             },
         )

build-support/bin/external_tool_upgrade_test.py

@@ -3,9 +3,151 @@
 import doctest
 
 import external_tool_upgrade
+from external_tool_upgrade import ExternalToolVersion, filter_versions_by_constraint
+from packaging.version import Version
 
 
 def test_docs() -> None:
     failure_count, test_count = doctest.testmod(external_tool_upgrade)
     assert test_count > 0
     assert failure_count == 0
+
+
+def test_filter_fetched_versions_with_constraint() -> None:
+    fetched = [
+        ExternalToolVersion("5.0", "linux_x86_64", "abc", 100),
+        ExternalToolVersion("6.0", "linux_x86_64", "def", 200),
+        ExternalToolVersion("6.1", "linux_x86_64", "ghi", 300),
+    ]
+
+    filtered = filter_versions_by_constraint(fetched, ">=6.0")
+
+    assert len(filtered) == 2
+    assert all(isinstance(v, ExternalToolVersion) for v in filtered)
+    assert {v.version for v in filtered} == {"6.0", "6.1"}
+
+
+def test_filter_versions_by_constraint_none() -> None:
+    versions = [
+        ExternalToolVersion("5.0", "cowsay", "abc", 100),
+        ExternalToolVersion("6.0", "cowsay", "def", 200),
+    ]
+    result = filter_versions_by_constraint(versions, None)
+    assert result == versions
+
+
+def test_filter_versions_by_constraint_basic() -> None:
+    versions = [
+        ExternalToolVersion("3.0", "cowsay", "abc", 100),
+        ExternalToolVersion("4.0", "cowsay", "def", 200),
+        ExternalToolVersion("5.0", "cowsay", "ghi", 300),
+    ]
+    result = filter_versions_by_constraint(versions, ">=4.0,<5.0")
+    assert len(result) == 1
+    assert result[0].version == "4.0"
+
+
+def test_filter_versions_by_constraint_with_v_prefix() -> None:
+    versions = [
+        ExternalToolVersion("v5.0", "cowsay", "abc", 100),
+        ExternalToolVersion("v6.0", "cowsay", "def", 200),
+    ]
+    result = filter_versions_by_constraint(versions, ">5.0")
+    assert len(result) == 1
+    assert result[0].version == "v6.0"
+
+
+def test_filter_versions_by_constraint_no_matches() -> None:
+    versions = [
+        ExternalToolVersion("6.1", "cowsay", "abc", 100),
+    ]
+    result = filter_versions_by_constraint(versions, ">7.0")
+    assert result == []
+
+
+def test_filter_versions_by_constraint_multiple_matches() -> None:
+    versions = [
+        ExternalToolVersion("3.0", "cowsay", "abc", 100),
+        ExternalToolVersion("4.0", "cowsay", "def", 200),
+        ExternalToolVersion("5.0", "cowsay", "ghi", 250),
+        ExternalToolVersion("6.0", "cowsay", "jkl", 300),
+    ]
+    result = filter_versions_by_constraint(versions, ">4.0,<6.0")
+    assert len(result) == 1
+    assert result[0].version == "5.0"
+
+
+def _select_default_version_with_constraint(
+    known_versions: list[ExternalToolVersion],
+    current_default: str,
+    constraint: str,
+) -> str:
+    """Helper that mirrors the upgrade logic in main().
+
+    Returns the new default_version based on the constraint and current default. Only upgrades if
+    the newest matching version is greater than current default.
+    """
+    filtered = filter_versions_by_constraint(known_versions, constraint)
+    if not filtered:
+        return current_default
+
+    current = Version(current_default.lstrip("v"))
+    newest_matching = Version(filtered[0].version.lstrip("v"))
+
+    if newest_matching > current:
+        return filtered[0].version
+    return current_default
+
+
+def test_version_constraint_upgrades_when_newer_version_available() -> None:
+    known_versions = [
+        ExternalToolVersion("6.1", "cowsay", "abc", 100),
+        ExternalToolVersion("6.0", "cowsay", "def", 200),
+        ExternalToolVersion("5.0", "cowsay", "ghi", 300),
+        ExternalToolVersion("4.0", "cowsay", "jkl", 400),
+    ]
+    current_default = "5.0"
+    constraint = ">=6.0,<7"
+
+    result = _select_default_version_with_constraint(known_versions, current_default, constraint)
+    assert result == "6.1"
+
+
+def test_version_constraint_no_upgrade_when_no_newer_matching_version() -> None:
+    known_versions = [
+        ExternalToolVersion("6.1", "cowsay", "abc", 100),
+        ExternalToolVersion("6.0", "cowsay", "def", 200),
+        ExternalToolVersion("5.0", "cowsay", "ghi", 300),
+        ExternalToolVersion("4.0", "cowsay", "jkl", 400),
+    ]
+    current_default = "6.0"
+    constraint = ">=3.0,<5.0"
+
+    result = _select_default_version_with_constraint(known_versions, current_default, constraint)
+    assert result == "6.0"
+
+
+def test_version_constraint_no_upgrade_when_already_at_newest_matching() -> None:
+    known_versions = [
+        ExternalToolVersion("6.1", "cowsay", "abc", 100),
+        ExternalToolVersion("6.0", "cowsay", "def", 200),
+        ExternalToolVersion("5.0", "cowsay", "ghi", 300),
+    ]
+    current_default = "6.0"
+    constraint = ">=5.0,<6.1"
+
+    result = _select_default_version_with_constraint(known_versions, current_default, constraint)
+    assert result == "6.0"
+
+
+def test_version_constraint_with_v_prefix_upgrades_correctly() -> None:
+    known_versions = [
+        ExternalToolVersion("v6.0", "cowsay", "abc", 100),
+        ExternalToolVersion("v5.0", "cowsay", "def", 200),
+        ExternalToolVersion("v4.0", "cowsay", "ghi", 300),
+    ]
+    current_default = "v4.0"
+    constraint = ">4.0,<6.0"
+
+    result = _select_default_version_with_constraint(known_versions, current_default, constraint)
+    assert result == "v5.0"