feat(py_console_script_binary)!: entry points with custom dependencies

.bazelrc

@@ -3,8 +3,8 @@
 # This lets us glob() up all the files inside the examples to make them inputs to tests
 # (Note, we cannot use `common --deleted_packages` because the bazel version command doesn't support it)
 # To update these lines, run tools/bazel_integration_test/update_deleted_packages.sh
-build --deleted_packages=examples/build_file_generation,examples/build_file_generation/random_number_generator,examples/bzlmod,examples/bzlmod_build_file_generation,examples/bzlmod_build_file_generation/other_module/other_module/pkg,examples/bzlmod_build_file_generation/runfiles,examples/bzlmod/entry_point,examples/bzlmod/libs/my_lib,examples/bzlmod/other_module,examples/bzlmod/other_module/other_module/pkg,examples/bzlmod/runfiles,examples/bzlmod/tests,examples/bzlmod/tests/other_module,examples/bzlmod/whl_mods,examples/multi_python_versions/libs/my_lib,examples/multi_python_versions/requirements,examples/multi_python_versions/tests,examples/pip_install,examples/pip_parse,examples/pip_parse_vendored,examples/pip_repository_annotations,examples/py_proto_library,tests/compile_pip_requirements,tests/compile_pip_requirements_test_from_external_workspace,tests/ignore_root_user_error,tests/pip_repository_entry_points
-query --deleted_packages=examples/build_file_generation,examples/build_file_generation/random_number_generator,examples/bzlmod,examples/bzlmod_build_file_generation,examples/bzlmod_build_file_generation/other_module/other_module/pkg,examples/bzlmod_build_file_generation/runfiles,examples/bzlmod/entry_point,examples/bzlmod/libs/my_lib,examples/bzlmod/other_module,examples/bzlmod/other_module/other_module/pkg,examples/bzlmod/runfiles,examples/bzlmod/tests,examples/bzlmod/tests/other_module,examples/bzlmod/whl_mods,examples/multi_python_versions/libs/my_lib,examples/multi_python_versions/requirements,examples/multi_python_versions/tests,examples/pip_install,examples/pip_parse,examples/pip_parse_vendored,examples/pip_repository_annotations,examples/py_proto_library,tests/compile_pip_requirements,tests/compile_pip_requirements_test_from_external_workspace,tests/ignore_root_user_error,tests/pip_repository_entry_points
+build --deleted_packages=examples/build_file_generation,examples/build_file_generation/random_number_generator,examples/bzlmod,examples/bzlmod/entry_points,examples/bzlmod/entry_points/tests,examples/bzlmod/libs/my_lib,examples/bzlmod/other_module,examples/bzlmod/other_module/other_module/pkg,examples/bzlmod/runfiles,examples/bzlmod/tests,examples/bzlmod/tests/other_module,examples/bzlmod/whl_mods,examples/bzlmod_build_file_generation,examples/bzlmod_build_file_generation/other_module/other_module/pkg,examples/bzlmod_build_file_generation/runfiles,examples/multi_python_versions/libs/my_lib,examples/multi_python_versions/requirements,examples/multi_python_versions/tests,examples/pip_install,examples/pip_parse,examples/pip_parse_vendored,examples/pip_repository_annotations,examples/py_proto_library,tests/compile_pip_requirements,tests/compile_pip_requirements_test_from_external_workspace,tests/ignore_root_user_error,tests/pip_repository_entry_points
+query --deleted_packages=examples/build_file_generation,examples/build_file_generation/random_number_generator,examples/bzlmod,examples/bzlmod/entry_points,examples/bzlmod/entry_points/tests,examples/bzlmod/libs/my_lib,examples/bzlmod/other_module,examples/bzlmod/other_module/other_module/pkg,examples/bzlmod/runfiles,examples/bzlmod/tests,examples/bzlmod/tests/other_module,examples/bzlmod/whl_mods,examples/bzlmod_build_file_generation,examples/bzlmod_build_file_generation/other_module/other_module/pkg,examples/bzlmod_build_file_generation/runfiles,examples/multi_python_versions/libs/my_lib,examples/multi_python_versions/requirements,examples/multi_python_versions/tests,examples/pip_install,examples/pip_parse,examples/pip_parse_vendored,examples/pip_repository_annotations,examples/py_proto_library,tests/compile_pip_requirements,tests/compile_pip_requirements_test_from_external_workspace,tests/ignore_root_user_error,tests/pip_repository_entry_points
 
 test --test_output=errors
 

CHANGELOG.md

@@ -17,6 +17,20 @@ A brief description of the categories of changes:
 * Particular sub-systems are identified using parentheses, e.g. `(bzlmod)` or
   `(docs)`.
 
+## Unreleased
+
+### Added
+
+* (bzlmod, entry_point) Added
+  [`py_console_script_binary`](./docs/py_console_script_binary.md), which
+  allows adding custom dependencies to a package's entry points and customizing
+  the `py_binary` rule used to build it.
+
+### Removed
+
+* (bzlmod) The `entry_point` macro is no longer supported and has been removed
+  in favour of the `py_console_script_binary` macro for `bzlmod` users.
+
 ## [0.25.0] - 2023-08-22
 
 ### Changed

docs/BUILD.bazel

@@ -27,6 +27,7 @@ _DOCS = {
     "pip_repository": "//docs:pip-repository",
     "py_cc_toolchain": "//docs:py_cc_toolchain-docs",
     "py_cc_toolchain_info": "//docs:py_cc_toolchain_info-docs",
+    "py_console_script_binary": "//docs:py-console-script-binary",
     "python": "//docs:core-docs",
 }
 
@@ -128,6 +129,16 @@ stardoc(
     ],
 )
 
+stardoc(
+    name = "py-console-script-binary",
+    out = "py_console_script_binary.md_",
+    input = "//python/entry_points:py_console_script_binary.bzl",
+    target_compatible_with = _NOT_WINDOWS,
+    deps = [
+        "//python/entry_points:py_console_script_binary_bzl",
+    ],
+)
+
 stardoc(
     name = "packaging-docs",
     out = "packaging.md_",

examples/bzlmod/MODULE.bazel

@@ -113,10 +113,7 @@ pip.parse(
         "@whl_mods_hub//:wheel.json": "wheel",
     },
 )
-
-# NOTE: The pip_39 repo is only used because the plain `@pip` repo doesn't
-# yet support entry points; see https://github.com/bazelbuild/rules_python/issues/1262
-use_repo(pip, "pip", "pip_39")
+use_repo(pip, "pip")
 
 bazel_dep(name = "other_module", version = "", repo_name = "our_other_module")
 local_path_override(

examples/bzlmod/entry_points/BUILD.bazel

@@ -0,0 +1,33 @@
+load("@python_versions//3.9:defs.bzl", py_console_script_binary_3_9 = "py_console_script_binary")
+load("@rules_python//python/entry_points:py_console_script_binary.bzl", "py_console_script_binary")
+
+# This is how you can define a `pylint` entrypoint which uses the default python version.
+py_console_script_binary(
+    name = "pylint",
+    pkg = "@pip//pylint",
+    visibility = ["//entry_points:__subpackages__"],
+)
+
+# We can also specify extra dependencies for the binary, which is useful for
+# tools like flake8, pylint, pytest, which have plugin discovery methods.
+py_console_script_binary(
+    name = "pylint_with_deps",
+    pkg = "@pip//pylint",
+    # Because `pylint` has multiple console_scripts available, we have to
+    # specify which we want if the name of the target name 'pylint_with_deps'
+    # cannot be used to guess the entry_point script.
+    script = "pylint",
+    visibility = ["//entry_points:__subpackages__"],
+    deps = [
+        # One can add extra dependencies to the entry point.
+        "@pip//pylint_print",
+    ],
+)
+
+# A specific Python version can be forced by using the generated version-aware
+# wrappers, e.g. to force Python 3.9:
+py_console_script_binary_3_9(
+    name = "yamllint",
+    pkg = "@pip//yamllint:pkg",
+    visibility = ["//entry_points:__subpackages__"],
+)

examples/bzlmod/entry_points/tests/BUILD.bazel

@@ -0,0 +1,63 @@
+load("@bazel_skylib//rules:run_binary.bzl", "run_binary")
+load("@rules_python//python:defs.bzl", "py_test")
+
+# Below are targets for testing the `py_console_script_binary` feature and are
+# not part of the example how to use the feature.
+
+# And a test that we can correctly run `pylint --version`
+py_test(
+    name = "pylint_test",
+    srcs = ["pylint_test.py"],
+    data = ["//entry_points:pylint"],
+    env = {
+        "ENTRY_POINT": "$(rlocationpath //entry_points:pylint)",
+    },
+    deps = ["@rules_python//python/runfiles"],
+)
+
+# Next run pylint on the file to generate a report.
+run_binary(
+    name = "pylint_report",
+    srcs = [
+        ":file_with_pylint_errors.py",
+    ],
+    outs = ["pylint_report.txt"],
+    args = [
+        "--output-format=text:$(location pylint_report.txt)",
+        "--load-plugins=pylint_print",
+        # The `exit-zero` ensures that `run_binary` is successful even though there are lint errors.
+        # We check the generated report in the test below.
+        "--exit-zero",
+        "$(location :file_with_pylint_errors.py)",
+    ],
+    env = {
+        # otherwise it may try to create ${HOME}/.cache/pylint
+        "PYLINTHOME": "./.pylint_home",
+    },
+    tool = "//entry_points:pylint_with_deps",
+)
+
+py_test(
+    name = "pylint_deps_test",
+    srcs = ["pylint_deps_test.py"],
+    data = [
+        ":pylint_report",
+        "//entry_points:pylint_with_deps",
+    ],
+    env = {
+        "ENTRY_POINT": "$(rlocationpath //entry_points:pylint_with_deps)",
+        "PYLINT_REPORT": "$(rlocationpath :pylint_report)",
+    },
+    deps = ["@rules_python//python/runfiles"],
+)
+
+# And a test to check that yamllint works
+py_test(
+    name = "yamllint_test",
+    srcs = ["yamllint_test.py"],
+    data = ["//entry_points:yamllint"],
+    env = {
+        "ENTRY_POINT": "$(rlocationpath //entry_points:yamllint)",
+    },
+    deps = ["@rules_python//python/runfiles"],
+)

examples/bzlmod/entry_points/tests/file_with_pylint_errors.py

@@ -0,0 +1,6 @@
+"""
+A file to demonstrate the pylint-print checker works.
+"""
+
+if __name__ == "__main__":
+    print("Hello, World!")

examples/bzlmod/entry_points/tests/pylint_deps_test.py

@@ -0,0 +1,72 @@
+# Copyright 2023 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.
+
+import os
+import pathlib
+import subprocess
+import tempfile
+import unittest
+
+from python.runfiles import runfiles
+
+
+class ExampleTest(unittest.TestCase):
+    def __init__(self, *args, **kwargs):
+        self.maxDiff = None
+
+        super().__init__(*args, **kwargs)
+
+    def test_pylint_entry_point(self):
+        rlocation_path = os.environ.get("ENTRY_POINT")
+        assert (
+            rlocation_path is not None
+        ), "expected 'ENTRY_POINT' env variable to be set to rlocation of the tool"
+
+        entry_point = pathlib.Path(runfiles.Create().Rlocation(rlocation_path))
+        self.assertTrue(entry_point.exists(), f"'{entry_point}' does not exist")
+
+        # Let's run the entrypoint and check the tool version.
+        #
+        # NOTE @aignas 2023-08-24: the Windows python launcher with Python 3.9 and bazel 6 is not happy if we start
+        # passing extra files via `subprocess.run` and it starts to fail with an error that the file which is the
+        # entry_point cannot be found. However, just calling `--version` seems to be fine.
+        proc = subprocess.run(
+            [str(entry_point), "--version"],
+            check=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+        )
+        self.assertEqual(
+            "",
+            proc.stderr.decode("utf-8").strip(),
+        )
+        self.assertRegex(proc.stdout.decode("utf-8").strip(), "^pylint 2\.15\.9")
+
+    def test_pylint_report_has_expected_warnings(self):
+        rlocation_path = os.environ.get("PYLINT_REPORT")
+        assert (
+            rlocation_path is not None
+        ), "expected 'PYLINT_REPORT' env variable to be set to rlocation of the report"
+
+        pylint_report = pathlib.Path(runfiles.Create().Rlocation(rlocation_path))
+        self.assertTrue(pylint_report.exists(), f"'{pylint_report}' does not exist")
+
+        self.assertRegex(
+            pylint_report.read_text().strip(),
+            "W8201: Logging should be used instead of the print\(\) function\. \(print-function\)",
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()