Merge branch 'main' into refactor/namespace-pkg-star

Author: aignas

CHANGELOG.md

@@ -91,6 +91,7 @@ END_UNRELEASED_TEMPLATE
   also retrieved from the URL as opposed to only the `--hash` parameter. Fixes
   [#2363](https://github.com/bazel-contrib/rules_python/issues/2363).
 * (pypi) `whl_library` now infers file names from its `urls` attribute correctly.
+* (py_test, py_binary) Allow external files to be used for main
 
 {#v0-0-0-added}
 ### Added

docs/BUILD.bazel

@@ -113,6 +113,7 @@ sphinx_stardocs(
         "//python/private:builders_util_bzl",
         "//python/private:py_binary_rule_bzl",
         "//python/private:py_cc_toolchain_rule_bzl",
+        "//python/private:py_info_bzl",
         "//python/private:py_library_rule_bzl",
         "//python/private:py_runtime_rule_bzl",
         "//python/private:py_test_rule_bzl",

docs/_includes/py_console_script_binary.md

@@ -48,6 +48,26 @@ py_console_script_binary(
 )
 ```
 
+#### Adding a Shebang Line
+
+You can specify a shebang line for the generated binary, useful for Unix-like
+systems where the shebang line determines which interpreter is used to execute
+the script, per [PEP441]:
+
+```starlark
+load("@rules_python//python/entry_points:py_console_script_binary.bzl", "py_console_script_binary")
+
+py_console_script_binary(
+    name = "black",
+    pkg = "@pip//black",
+    shebang = "#!/usr/bin/env python3",
+)
+```
+
+Note that to execute via the shebang line, you need to ensure the specified
+Python interpreter is available in the environment.
+
+
 #### Using a specific Python Version directly from a Toolchain
 :::{deprecated} 1.1.0
 The toolchain specific `py_binary` and `py_test` symbols are aliases to the regular rules. 
@@ -70,4 +90,5 @@ py_console_script_binary(
 ```
 
 [specification]: https://packaging.python.org/en/latest/specifications/entry-points/
-[`py_console_script_binary.binary_rule`]: #py_console_script_binary_binary_rule
+[`py_console_script_binary.binary_rule`]: #py_console_script_binary_binary_rule
+[PEP441]: https://peps.python.org/pep-0441/#minimal-tooling-the-zipapp-module

docs/api/rules_python/python/bin/index.md

@@ -10,7 +10,8 @@
 A target to directly run a Python interpreter.
 
 By default, it uses the Python version that toolchain resolution matches
-(typically the one marked `is_default=True` in `MODULE.bazel`).
+(typically the one set with `python.defaults(python_version = ...)` in
+`MODULE.bazel`).
 
 This runs a Python interpreter in a similar manner as when running `python3`
 on the command line. It can be invoked using `bazel run`. Remember that in

docs/toolchains.md

@@ -44,7 +44,8 @@ you should read the dev-only library module section.
 bazel_dep(name="rules_python", version=...)
 python = use_extension("@rules_python//python/extensions:python.bzl", "python")
 
-python.toolchain(python_version = "3.12", is_default = True)
+python.defaults(python_version = "3.12")
+python.toolchain(python_version = "3.12")
 ```
 
 ### Library modules
@@ -72,7 +73,8 @@ python = use_extension(
     dev_dependency = True
 )
 
-python.toolchain(python_version = "3.12", is_default=True)
+python.defaults(python_version = "3.12")
+python.toolchain(python_version = "3.12")
 ```
 
 #### Library modules without version constraints
@@ -161,9 +163,13 @@ Multiple versions can be specified and used within a single build.
 # MODULE.bazel
 python = use_extension("@rules_python//python/extensions:python.bzl", "python")
 
+python.defaults(
+    # The environment variable takes precedence if set.
+    python_version = "3.11",
+    python_version_env = "BAZEL_PYTHON_VERSION",
+)
 python.toolchain(
     python_version = "3.11",
-    is_default = True,
 )
 
 python.toolchain(
@@ -264,7 +270,8 @@ bazel_dep(name = "rules_python", version = "0.40.0")
 
 python = use_extension("@rules_python//python/extensions:python.bzl", "python")
 
-python.toolchain(is_default = True, python_version = "3.10")
+python.defaults(python_version = "3.10")
+python.toolchain(python_version = "3.10")
 
 use_repo(python, "python_3_10", "python_3_10_host")
 ```

examples/bzlmod/MODULE.bazel

@@ -28,10 +28,13 @@ bazel_dep(name = "rules_rust", version = "0.54.1")
 # We next initialize the python toolchain using the extension.
 # You can set different Python versions in this block.
 python = use_extension("@rules_python//python/extensions:python.bzl", "python")
+python.defaults(
+    # Use python.defaults if you have defined multiple toolchain versions.
+    python_version = "3.9",
+    python_version_env = "BAZEL_PYTHON_VERSION",
+)
 python.toolchain(
     configure_coverage_tool = True,
-    # Only set when you have multiple toolchain versions.
-    is_default = True,
     python_version = "3.9",
 )
 

examples/bzlmod/other_module/MODULE.bazel

@@ -25,14 +25,16 @@ PYTHON_NAME_39 = "python_3_9"
 PYTHON_NAME_311 = "python_3_11"
 
 python = use_extension("@rules_python//python/extensions:python.bzl", "python")
+python.defaults(
+    # In a submodule this is ignored
+    python_version = "3.11",
+)
 python.toolchain(
     configure_coverage_tool = True,
     python_version = "3.9",
 )
 python.toolchain(
     configure_coverage_tool = True,
-    # In a submodule this is ignored
-    is_default = True,
     python_version = "3.11",
 )
 

examples/bzlmod/requirements_lock_3_9.txt

@@ -262,9 +262,9 @@ s3cmd==2.1.0 \
     --hash=sha256:49cd23d516b17974b22b611a95ce4d93fe326feaa07320bd1d234fed68cbccfa \
     --hash=sha256:966b0a494a916fc3b4324de38f089c86c70ee90e8e1cae6d59102103a4c0cc03
     # via -r examples/bzlmod/requirements.in
-setuptools==65.6.3 \
-    --hash=sha256:57f6f22bde4e042978bcd50176fdb381d7c21a9efa4041202288d3737a0c6a54 \
-    --hash=sha256:a7620757bf984b58deaf32fc8a4577a9bbc0850cf92c20e1ce41c38c19e5fb75
+setuptools==78.1.1 \
+    --hash=sha256:c3a9c4211ff4c309edb8b8c4f1cbfa7ae324c4ba9f91ff254e3d305b9fd54561 \
+    --hash=sha256:fcc17fd9cd898242f6b4adfaca46137a9edef687f43e6f78469692a5e70d851d
     # via
     #   babel
     #   yamllint

examples/bzlmod_build_file_generation/MODULE.bazel

@@ -46,9 +46,13 @@ python = use_extension("@rules_python//python/extensions:python.bzl", "python")
 
 # We next initialize the python toolchain using the extension.
 # You can set different Python versions in this block.
+python.defaults(
+    # The environment variable takes precedence if set.
+    python_version = "3.9",
+    python_version_env = "BAZEL_PYTHON_VERSION",
+)
 python.toolchain(
     configure_coverage_tool = True,
-    is_default = True,
     python_version = "3.9",
 )
 

examples/multi_python_versions/MODULE.bazel

@@ -17,8 +17,6 @@ python.defaults(
 )
 python.toolchain(
     configure_coverage_tool = True,
-    # Only set when you have mulitple toolchain versions.
-    is_default = True,
     python_version = "3.9",
 )
 python.toolchain(