rework the symbol deprecation and add tests to ensure that we are still working

Author: aignas

python/config_settings/transition.bzl

@@ -21,54 +21,20 @@ of them should be changed to load the regular rules directly.
 :::
 """
 
-load("@rules_python_internal//:rules_python_config.bzl", "config")
 load("//python:py_binary.bzl", _py_binary = "py_binary")
 load("//python:py_test.bzl", _py_test = "py_test")
+load("//python/private:deprecation.bzl", "with_deprecation")
+load("//python/private:text_util.bzl", "render")
 
-_DEPRECATION_MESSAGE = """
-The '{name}' symbol in @{deprecated}
-is deprecated. It is an alias to the regular rule; use it directly instead:
-
-load("@rules_python//python{load_name}.bzl", "{name}")
-
-{name}(
-    # ...
-    python_version = "{python_version}",
-    # ...
-)
-"""
-
-def with_deprecation(kwargs, *, symbol_name, python_version, load_name = None, deprecated = "rules_python//python/config_settings:transition.bzl"):
-    """An internal function to propagate the deprecation warning.
-
-    This is not an API that should be used outside `rules_python`.
-
-    Args:
-        kwargs: Arguments to modify.
-        symbol_name: {type}`str` the symbol name that is deprecated.
-        python_version: {type}`str` the python version to be used.
-        load_name: {type}`str` the load location under `//python`. Should start
-            either with `/` or `:`. Defaults to `:<symbol_name>`.
-        deprecated: {type}`str` the symbol import location that we are deprecating.
-
-    Returns:
-        The kwargs to be used in the macro creation.
-    """
-
-    if config.enable_deprecation_warnings:
-        load_name = load_name or (":" + symbol_name)
-
-        deprecation = _DEPRECATION_MESSAGE.format(
-            name = symbol_name,
-            load_name = load_name,
-            python_version = python_version,
-            deprecated = deprecated,
-        )
-        if kwargs.get("deprecation"):
-            deprecation = kwargs.get("deprecation") + "\n\n" + deprecation
-        kwargs["deprecation"] = deprecation
+def _with_deprecation(kwargs, *, name, python_version):
     kwargs["python_version"] = python_version
-    return kwargs
+    return with_deprecation.symbol(
+        kwargs,
+        symbol_name = name,
+        old_load = "@rules_python//python/config_settings:transition.bzl",
+        new_load = "@rules_python//python:{}.bzl".format(name),
+        snippet = render.call(name, **{k: repr(v) for k, v in kwargs.items()}),
+    )
 
 def py_binary(**kwargs):
     """[DEPRECATED] Deprecated alias for py_binary.
@@ -77,12 +43,12 @@ def py_binary(**kwargs):
         **kwargs: keyword args forwarded onto {obj}`py_binary`.
     """
 
-    _py_binary(**with_deprecation(kwargs, name = "py_binary", python_version = kwargs.get("python_version")))
+    _py_binary(**_with_deprecation(kwargs, name = "py_binary", python_version = kwargs.get("python_version")))
 
 def py_test(**kwargs):
     """[DEPRECATED] Deprecated alias for py_test.
 
     Args:
         **kwargs: keyword args forwarded onto {obj}`py_binary`.
     """
-    _py_test(**with_deprecation(kwargs, name = "py_test", python_version = kwargs.get("python_version")))
+    _py_test(**_with_deprecation(kwargs, name = "py_test", python_version = kwargs.get("python_version")))

python/private/BUILD.bazel

@@ -138,6 +138,14 @@ bzl_library(
     ],
 )
 
+bzl_library(
+    name = "deprecation_bzl",
+    srcs = ["deprecation.bzl"],
+    deps = [
+        "@rules_python_internal//:rules_python_config_bzl",
+    ],
+)
+
 bzl_library(
     name = "enum_bzl",
     srcs = ["enum.bzl"],

python/private/deprecation.bzl

@@ -0,0 +1,59 @@
+# Copyright 2024 The Bazel Authors. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Helper functions to deprecation utilities.
+"""
+
+load("@rules_python_internal//:rules_python_config.bzl", "config")
+
+_DEPRECATION_MESSAGE = """
+The '{name}' symbol in '{old_load}'
+is deprecated. It is an alias to the regular rule; use it directly instead:
+
+load("{new_load}", "{name}")
+
+{snippet}
+"""
+
+def _symbol(kwargs, *, symbol_name, new_load, old_load, snippet = ""):
+    """An internal function to propagate the deprecation warning.
+
+    This is not an API that should be used outside `rules_python`.
+
+    Args:
+        kwargs: Arguments to modify.
+        symbol_name: {type}`str` the symbol name that is deprecated.
+        new_load: {type}`str` the new load location under `//`.
+        old_load: {type}`str` the symbol import location that we are deprecating.
+        snippet: {type}`str` the usage snippet of the new symbol.
+
+    Returns:
+        The kwargs to be used in the macro creation.
+    """
+
+    if config.enable_deprecation_warnings:
+        deprecation = _DEPRECATION_MESSAGE.format(
+            name = symbol_name,
+            old_load = old_load,
+            new_load = new_load,
+            snippet = snippet,
+        )
+        if kwargs.get("deprecation"):
+            deprecation = kwargs.get("deprecation") + "\n\n" + deprecation
+        kwargs["deprecation"] = deprecation
+    return kwargs
+
+with_deprecation = struct(
+    symbol = _symbol,
+)

python/private/internal_config_repo.bzl

@@ -18,6 +18,8 @@ such as globals available to Bazel versions, or propagating user environment
 settings for rules to later use.
 """
 
+load(":repo_utils.bzl", "repo_utils")
+
 _ENABLE_PYSTAR_ENVVAR_NAME = "RULES_PYTHON_ENABLE_PYSTAR"
 _ENABLE_PYSTAR_DEFAULT = "1"
 _ENABLE_DEPRECATION_WARNINGS_ENVVAR_NAME = "RULES_PYTHON_DEPRECATION_WARNINGS"
@@ -116,4 +118,4 @@ internal_config_repo = repository_rule(
 )
 
 def _bool_from_environ(rctx, key, default):
-    return bool(int(rctx.os.environ.get(key, default)))
+    return bool(int(repo_utils.getenv(rctx, key, default)))

python/private/toolchains_repo.bzl

@@ -151,61 +151,37 @@ toolchain_aliases(
     rctx.file("defs.bzl", content = """\
 # Generated by python/private/toolchains_repo.bzl
 
-load("{rules_python}//python/config_settings:transition.bzl", "with_deprecation")
+load("{rules_python}//python:pip.bzl", _compile_pip_requirements = "compile_pip_requirements")
+load("{rules_python}//python/private:deprecation.bzl", "with_deprecation")
+load("{rules_python}//python/private:text_util.bzl", "render")
 load("{rules_python}//python:py_binary.bzl", _py_binary = "py_binary")
 load("{rules_python}//python:py_test.bzl", _py_test = "py_test")
 load(
     "{rules_python}//python/entry_points:py_console_script_binary.bzl",
     _py_console_script_binary = "py_console_script_binary",
 )
-load("{rules_python}//python:pip.bzl", _compile_pip_requirements = "compile_pip_requirements")
 
-def py_binary(**kwargs):
-    return _py_binary(
-        **with_deprecation(
-            kwargs,
-            symbol_name = "py_binary",
-            python_version = "{python_version}",
-            deprecated = "@{name}//:defs.bzl",
-        ),
+def _with_deprecation(kwargs, *, name):
+    kwargs["python_version"] = "{python_version}"
+    return with_deprecation.symbol(
+        kwargs,
+        symbol_name = name,
+        old_load = "@{name}//:defs.bzl",
+        new_load = "@rules_python//python:{{}}.bzl".format(name),
+        snippet = render.call(name, **{{k: repr(v) for k,v in kwargs.items()}})
     )
 
-def py_console_script_binary(name, **kwargs):
-    return _py_console_script_binary(
-        name = name,
-        binary_rule = _py_binary,
-        **with_deprecation(
-            kwargs,
-            symbol_name = "py_console_script_binary",
-            load_name = "/entry_points:py_console_script_binary",
-            python_version = "{python_version}",
-            deprecated = "@{name}//:defs.bzl",
-        ),
-    )
+def py_binary(**kwargs):
+    return _py_binary(**_with_deprecation(kwargs, name = "py_binary"))
 
-def py_test(name, **kwargs):
-    return _py_test(
-        name = name,
-        **with_deprecation(
-            kwargs,
-            symbol_name = "py_test",
-            python_version = "{python_version}",
-            deprecated = "@{name}//:defs.bzl",
-        ),
-    )
+def py_console_script_binary(**kwargs):
+    return _py_console_script_binary(**_with_deprecation(kwargs, name = "py_console_script_binary"))
 
-def compile_pip_requirements(name, **kwargs):
-    return _compile_pip_requirements(
-        name = name,
-        **with_deprecation(
-            kwargs,
-            symbol_name = "compile_pip_requirements",
-            load_name = "pip",
-            python_version = "{python_version}",
-            deprecated = "@{name}//:defs.bzl",
-        ),
-    )
+def py_test(**kwargs):
+    return _py_test(**_with_deprecation(kwargs, name = "py_test"))
 
+def compile_pip_requirements(**kwargs):
+    return _compile_pip_requirements(**_with_deprecation(kwargs, name = "compile_pip_requirements"))
 """.format(
         name = rctx.attr.name,
         python_version = rctx.attr.python_version,
@@ -332,66 +308,42 @@ def _multi_toolchain_aliases_impl(rctx):
         rctx.file(file, content = """\
 # Generated by python/private/toolchains_repo.bzl
 
-load("@@{rules_python}//python/config_settings:transition.bzl", "with_deprecation")
-load("@@{rules_python}//python:py_binary.bzl", _py_binary = "py_binary")
-load("@@{rules_python}//python:py_test.bzl", _py_test = "py_test")
+load("{rules_python}//python:pip.bzl", _compile_pip_requirements = "compile_pip_requirements")
+load("{rules_python}//python/private:deprecation.bzl", "with_deprecation")
+load("{rules_python}//python/private:text_util.bzl", "render")
+load("{rules_python}//python:py_binary.bzl", _py_binary = "py_binary")
+load("{rules_python}//python:py_test.bzl", _py_test = "py_test")
 load(
-    "@@{rules_python}//python/entry_points:py_console_script_binary.bzl",
+    "{rules_python}//python/entry_points:py_console_script_binary.bzl",
     _py_console_script_binary = "py_console_script_binary",
 )
-load("@@{rules_python}//python:pip.bzl", _compile_pip_requirements = "compile_pip_requirements")
 
-def py_binary(**kwargs):
-    return _py_binary(
-        **with_deprecation(
-            kwargs,
-            symbol_name = "py_binary",
-            python_version = "{python_version}",
-            deprecated = "@{name}//{python_version}:defs.bzl",
-        ),
+def _with_deprecation(kwargs, *, name):
+    kwargs["python_version"] = "{python_version}"
+    return with_deprecation.symbol(
+        kwargs,
+        symbol_name = name,
+        old_load = "@{name}//{python_version}:defs.bzl",
+        new_load = "@rules_python//python:{{}}.bzl".format(name),
+        snippet = render.call(name, **{{k: repr(v) for k,v in kwargs.items()}})
     )
 
-def py_console_script_binary(name, **kwargs):
-    return _py_console_script_binary(
-        name = name,
-        binary_rule = _py_binary,
-        **with_deprecation(
-            kwargs,
-            symbol_name = "py_console_script_binary",
-            load_name = "/entry_points:py_console_script_binary",
-            python_version = "{python_version}",
-            deprecated = "@{name}//{python_version}:defs.bzl",
-        ),
-    )
+def py_binary(**kwargs):
+    return _py_binary(**_with_deprecation(kwargs, name = "py_binary"))
 
-def py_test(name, **kwargs):
-    return _py_test(
-        name = name,
-        **with_deprecation(
-            kwargs,
-            symbol_name = "py_test",
-            python_version = "{python_version}",
-            deprecated = "@{name}//{python_version}:defs.bzl",
-        ),
-    )
+def py_console_script_binary(**kwargs):
+    return _py_console_script_binary(**_with_deprecation(kwargs, name = "py_console_script_binary"))
 
-def compile_pip_requirements(name, **kwargs):
-    return _compile_pip_requirements(
-        name = name,
-        **with_deprecation(
-            kwargs,
-            symbol_name = "compile_pip_requirements",
-            load_name = "pip",
-            python_version = "{python_version}",
-            deprecated = "@{name}//{python_version}:defs.bzl",
-        ),
-    )
+def py_test(**kwargs):
+    return _py_test(**_with_deprecation(kwargs, name = "py_test"))
 
+def compile_pip_requirements(**kwargs):
+    return _compile_pip_requirements(**_with_deprecation(kwargs, name = "compile_pip_requirements"))
 """.format(
             repository_name = repository_name,
             name = rctx.attr.name,
             python_version = python_version,
-            rules_python = rules_python,
+            rules_python = "@" + rules_python,
         ))
         rctx.file("{}/BUILD.bazel".format(python_version), "")