comment: add a more informative no match error text

python/private/render_pkg_aliases.bzl

@@ -20,6 +20,27 @@ load("//python/private:normalize_name.bzl", "normalize_name")
 load(":text_util.bzl", "render")
 load(":version_label.bzl", "version_label")
 
+_NO_MATCH_ERROR_MESSAGE_TEMPLATE = """\
+_NO_MATCH_ERROR = \"\"\"\\
+No matching wheel for current configuration's Python version.
+
+The current build configuration's Python version doesn't match any of the Python
+versions available for this wheel. This wheel supports the following Python versions:
+{supported_versions}
+
+As matched by the `@{rules_python}//python/config_settings:is_python_<version>`
+configuration settings.
+
+To determine the current configuration's Python version, run:
+    `bazel config <config id>` (shown further below)
+and look for
+    {rules_python}//python/config_settings:python_version
+
+If the value is missing, then the "default" Python version is being used,
+which has a "null" version value and will not match version constraints.
+\"\"\"\
+"""
+
 def _render_whl_library_alias(
         *,
         name,
@@ -72,9 +93,7 @@ def _render_whl_library_alias(
         )
         selects["//conditions:default"] = default_actual
     else:
-        no_match_error = "PyPI package is only available for versions: {}".format(
-            ",".join(versions),
-        )
+        no_match_error = "_NO_MATCH_ERROR"
 
     return render.alias(
         name = name,
@@ -85,24 +104,41 @@ def _render_whl_library_alias(
     )
 
 def _render_common_aliases(repo_name, name, versions = None, default_version = None, rules_python = None):
-    return "\n\n".join([
+    lines = [
         """package(default_visibility = ["//visibility:public"])""",
+    ]
+
+    if versions:
+        versions = sorted(versions)
+
+    if versions and not default_version:
+        lines.append(_NO_MATCH_ERROR_MESSAGE_TEMPLATE.format(
+            supported_versions = render.indent("\n".join(versions)),
+            rules_python = rules_python,
+        ))
+
+    lines.append(
         render.alias(
             name = name,
             actual = repr(":pkg"),
         ),
-    ] + [
-        _render_whl_library_alias(
-            name = target,
-            repo_name = repo_name,
-            dep = name,
-            target = target,
-            versions = versions,
-            default_version = default_version,
-            rules_python = rules_python,
-        )
-        for target in ["pkg", "whl", "data", "dist_info"]
-    ])
+    )
+    lines.extend(
+        [
+            _render_whl_library_alias(
+                name = target,
+                repo_name = repo_name,
+                dep = name,
+                target = target,
+                versions = versions,
+                default_version = default_version,
+                rules_python = rules_python,
+            )
+            for target in ["pkg", "whl", "data", "dist_info"]
+        ],
+    )
+
+    return "\n\n".join(lines)
 
 def render_pkg_aliases(*, repo_name, bzl_packages = None, whl_map = None, rules_python = None, default_version = None):
     """Create alias declarations for each PyPI package.

python/private/text_util.bzl

@@ -45,7 +45,7 @@ def _render_select(selects, *, no_match_error = None):
         args = "\n".join([
             "",
             _indent(dict_str),
-            _indent("no_match_error = {},".format(repr(no_match_error))),
+            _indent("no_match_error = {},".format(no_match_error)),
             "",
         ])
     else:

tests/pip_hub_repository/render_pkg_aliases/render_pkg_aliases_test.bzl

@@ -141,14 +141,34 @@ def _test_bzlmod_aliases_with_no_default_version(env):
         repo_name = "pypi",
         rules_python = "rules_python",
         whl_map = {
-            "bar-baz": ["3.2.3"],
+            "bar-baz": ["3.2.3", "3.1.3"],
         },
     )
 
-    want = {
-        "bar_baz/BUILD.bazel": """\
+    want_key = "bar_baz/BUILD.bazel"
+    want_content = """\
 package(default_visibility = ["//visibility:public"])
 
+_NO_MATCH_ERROR = \"\"\"\\
+No matching wheel for current configuration's Python version.
+
+The current build configuration's Python version doesn't match any of the Python
+versions available for this wheel. This wheel supports the following Python versions:
+    3.1.3
+    3.2.3
+
+As matched by the `@rules_python//python/config_settings:is_python_<version>`
+configuration settings.
+
+To determine the current configuration's Python version, run:
+    `bazel config <config id>` (shown further below)
+and look for
+    rules_python//python/config_settings:python_version
+
+If the value is missing, then the "default" Python version is being used,
+which has a "null" version value and will not match version constraints.
+\"\"\"
+
 alias(
     name = "bar_baz",
     actual = ":pkg",
@@ -158,44 +178,48 @@ alias(
     name = "pkg",
     actual = select(
         {
+            "@@rules_python//python/config_settings:is_python_3.1.3": "@pypi_31_bar_baz//:pkg",
             "@@rules_python//python/config_settings:is_python_3.2.3": "@pypi_32_bar_baz//:pkg",
         },
-        no_match_error = "PyPI package is only available for versions: 3.2.3",
+        no_match_error = _NO_MATCH_ERROR,
     ),
 )
 
 alias(
     name = "whl",
     actual = select(
         {
+            "@@rules_python//python/config_settings:is_python_3.1.3": "@pypi_31_bar_baz//:whl",
             "@@rules_python//python/config_settings:is_python_3.2.3": "@pypi_32_bar_baz//:whl",
         },
-        no_match_error = "PyPI package is only available for versions: 3.2.3",
+        no_match_error = _NO_MATCH_ERROR,
     ),
 )
 
 alias(
     name = "data",
     actual = select(
         {
+            "@@rules_python//python/config_settings:is_python_3.1.3": "@pypi_31_bar_baz//:data",
             "@@rules_python//python/config_settings:is_python_3.2.3": "@pypi_32_bar_baz//:data",
         },
-        no_match_error = "PyPI package is only available for versions: 3.2.3",
+        no_match_error = _NO_MATCH_ERROR,
     ),
 )
 
 alias(
     name = "dist_info",
     actual = select(
         {
+            "@@rules_python//python/config_settings:is_python_3.1.3": "@pypi_31_bar_baz//:dist_info",
             "@@rules_python//python/config_settings:is_python_3.2.3": "@pypi_32_bar_baz//:dist_info",
         },
-        no_match_error = "PyPI package is only available for versions: 3.2.3",
+        no_match_error = _NO_MATCH_ERROR,
     ),
-)""",
-    }
+)"""
 
-    env.expect.that_dict(actual).contains_exactly(want)
+    env.expect.that_collection(actual.keys()).contains_exactly([want_key])
+    env.expect.that_str(actual[want_key]).equals(want_content)
 
 _tests.append(_test_bzlmod_aliases_with_no_default_version)