Merge branch 'main' of https://github.com/bazel-contrib/rules_python into feat.custom.toolchain.override

Author: rickeylev

.python-version

@@ -0,0 +1 @@
+3.13.3

CHANGELOG.md

@@ -66,8 +66,8 @@ END_UNRELEASED_TEMPLATE
 * (rules) On Windows, {obj}`--bootstrap_impl=system_python` is forced. This
   allows setting `--bootstrap_impl=script` in bazelrc for mixed-platform
   environments.
-* (rules) {obj}`pip_compile` now generates a `.test` target. The `_test` target is deprecated
-  and will be removed in the next major release.
+* (rules) {obj}`compile_pip_requirements` now generates a `.test` target. The
+  `_test` target is deprecated and will be removed in the next major release.
   ([#2794](https://github.com/bazel-contrib/rules_python/issues/2794)
 * (py_wheel) py_wheel always creates zip64-capable wheel zips
 
@@ -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
@@ -102,6 +103,8 @@ END_UNRELEASED_TEMPLATE
 * (pypi) Starlark-based evaluation of environment markers (requirements.txt conditionals)
   available (not enabled by default) for improved multi-platform build support.
   Set the `RULES_PYTHON_ENABLE_PIPSTAR=1` environment variable to enable it.
+* (utils) Add a way to run a REPL for any `rules_python` target that returns
+  a `PyInfo` provider.
 * (toolchains) Arbitrary python-build-standalone runtimes can be registered
   and activated with custom flags. See the [Registering custom runtimes]
   docs and {obj}`single_version_platform_override()` API docs for more
@@ -192,7 +195,7 @@ END_UNRELEASED_TEMPLATE
   packages through SimpleAPI unless they are pulled through direct URL
   references. Fixes [#2023](https://github.com/bazel-contrib/rules_python/issues/2023).
   In case you see issues with `rules_python` being too eager to fetch the SimpleAPI
-  metadata, you can use the newly added {attr}`pip.parse.experimental_skip_sources`
+  metadata, you can use the newly added {attr}`pip.parse.simpleapi_skip`
   to skip metadata fetching for those packages.
 * (uv) A {obj}`lock` rule that is the replacement for the
   {obj}`compile_pip_requirements`. This may still have rough corners
@@ -253,7 +256,7 @@ END_UNRELEASED_TEMPLATE
 
 {#v1-3-0-added}
 ### Added
-* (python) {attr}`python.defaults` has been added to allow users to
+* (python) {obj}`python.defaults` has been added to allow users to
   set the default python version in the root module by reading the
   default version number from a file or an environment variable.
 * {obj}`//python/bin:python`: convenience target for directly running an
@@ -273,7 +276,7 @@ END_UNRELEASED_TEMPLATE
   and py_library rules
   ([#1647](https://github.com/bazel-contrib/rules_python/issues/1647))
 * (rules) Added env-var to allow additional interpreter args for stage1 bootstrap.
-  See {obj}`RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS` environment variable.
+  See {any}`RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS` environment variable.
   Only applicable for {obj}`--bootstrap_impl=script`.
 * (rules) Added {obj}`interpreter_args` attribute to `py_binary` and `py_test`,
   which allows pass arguments to the interpreter before the regular args.
@@ -379,7 +382,7 @@ END_UNRELEASED_TEMPLATE
   values. Fixes [#2466](https://github.com/bazel-contrib/rules_python/issues/2466).
 * (py_proto_library) Fix import paths in Bazel 8.
 * (whl_library) Now the changes to the dependencies are correctly tracked when
-  PyPI packages used in {bzl:obj}`whl_library` during the `repository_rule` phase
+  PyPI packages used in `whl_library` during the repository rule phase
   change. Fixes [#2468](https://github.com/bazel-contrib/rules_python/issues/2468).
 + (gazelle) Gazelle no longer ignores `setup.py` files by default. To restore
   this behavior, apply the `# gazelle:python_ignore_files setup.py` directive.
@@ -398,7 +401,7 @@ END_UNRELEASED_TEMPLATE
 * (pypi) Freethreaded packages are now fully supported in the
   {obj}`experimental_index_url` usage or the regular `pip.parse` usage.
   To select the free-threaded interpreter in the repo phase, please use
-  the documented [env](/environment-variables.html) variables.
+  the documented [env](environment-variables) variables.
   Fixes [#2386](https://github.com/bazel-contrib/rules_python/issues/2386).
 * (toolchains) Use the latest astrahl-sh toolchain release [20241206] for Python versions:
     * 3.9.21
@@ -492,7 +495,7 @@ Other changes:
   for the latest toolchain versions for each minor Python version. You can control
   the toolchain selection by using the
   {bzl:obj}`//python/config_settings:py_linux_libc` build flag.
-* (providers) Added {obj}`py_runtime_info.site_init_template` and
+* (providers) Added {obj}`PyRuntimeInfo.site_init_template` and
   {obj}`PyRuntimeInfo.site_init_template` for specifying the template to use to
   initialize the interpreter via venv startup hooks.
 * (runfiles) (Bazel 7.4+) Added support for spaces and newlines in runfiles paths
@@ -690,8 +693,8 @@ Other changes:
 * (bzlmod) The default value for the {obj}`--python_version` flag will now be
   always set to the default python toolchain version value.
 * (bzlmod) correctly wire the {attr}`pip.parse.extra_pip_args` all the
-  way to {obj}`whl_library`. What is more we will pass the `extra_pip_args` to
-  {obj}`whl_library` for `sdist` distributions when using
+  way to `whl_library`. What is more we will pass the `extra_pip_args` to
+  `whl_library` for `sdist` distributions when using
   {attr}`pip.parse.experimental_index_url`. See
   [#2239](https://github.com/bazel-contrib/rules_python/issues/2239).
 * (whl_filegroup): Provide per default also the `RECORD` file
@@ -739,8 +742,8 @@ Other changes:
 
 {#v0-37-0-removed}
 ### Removed
-* (precompiling) {obj}`--precompile_add_to_runfiles` has been removed.
-* (precompiling) {obj}`--pyc_collection` has been removed. The `pyc_collection`
+* (precompiling) `--precompile_add_to_runfiles` has been removed.
+* (precompiling) `--pyc_collection` has been removed. The `pyc_collection`
   attribute now bases its default on {obj}`--precompile`.
 * (precompiling) The {obj}`precompile=if_generated_source` value has been removed.
 * (precompiling) The {obj}`precompile_source_retention=omit_if_generated_source` value has been removed.
@@ -792,7 +795,7 @@ Other changes:
   in extra_requires in py_wheel rule.
 * (rules) Prevent pytest from trying run the generated stage2
   bootstrap .py file when using {obj}`--bootstrap_impl=script`
-* (toolchain) The {bzl:obj}`gen_python_config_settings` has been fixed to include
+* (toolchain) The `gen_python_config_settings` has been fixed to include
   the flag_values from the platform definitions.
 
 {#v0-36-0-added}
@@ -1207,9 +1210,9 @@ Other changes:
   depend on legacy labels instead of the hub repo aliases and you use the
   `experimental_requirement_cycles`, now is a good time to migrate.
 
-[python_default_visibility]: gazelle/README.md#directive-python_default_visibility
+[python_default_visibility]: https://github.com/bazel-contrib/rules_python/tree/main/gazelle/README.md#directive-python_default_visibility
 [test_file_pattern_issue]: https://github.com/bazel-contrib/rules_python/issues/1816
-[test_file_pattern_docs]: gazelle/README.md#directive-python_test_file_pattern
+[test_file_pattern_docs]: https://github.com/bazel-contrib/rules_python/tree/main/gazelle/README.md#directive-python_test_file_pattern
 [20240224]: https://github.com/indygreg/python-build-standalone/releases/tag/20240224.
 [20240415]: https://github.com/indygreg/python-build-standalone/releases/tag/20240415.
 

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/conf.py

@@ -125,6 +125,12 @@
 primary_domain = None  # The default is 'py', which we don't make much use of
 nitpicky = True
 
+nitpick_ignore_regex = [
+    # External xrefs aren't setup: ignore missing xref warnings
+    # External xrefs to sphinx isn't setup: ignore missing xref warnings
+    ("py:.*", "(sphinx|docutils|ast|enum|collections|typing_extensions).*"),
+]
+
 # --- Intersphinx configuration
 
 intersphinx_mapping = {

DEVELOPING.md renamed to docs/devguide.md

@@ -1,4 +1,4 @@
-# For Developers
+# Dev Guide
 
 This document covers tips and guidance for working on the rules_python code
 base. A primary audience for it is first time contributors.
@@ -39,7 +39,7 @@ more important for tests to balance understandability and maintainability.
 
 ### sh_py_run_test
 
-The [`sh_py_run_test`](tests/support/sh_py_run_test.bzl) rule is a helper to
+The {gh-path}`sh_py_run_test <tests/support/sh_py_run_test.bzl` rule is a helper to
 make it easy to run a Python program with custom build settings using a shell
 script to perform setup and verification. This is best to use when verifying
 behavior needs certain environment variables or directory structures to
@@ -56,6 +56,8 @@ Python binaries and tests with custom build flags. This is best to use when
 verifying behavior that requires specific flags to be set and when the program
 itself can verify the desired state.
 
+They are located in {gh-path}`tests/support/py_reconfig.bzl`
+
 When adding a test, you may find the flag you need to set isn't supported by
 the rule. To have it support setting a new flag:
 

docs/getting-started.md

@@ -7,7 +7,7 @@ and the older way of using `WORKSPACE`.
 It assumes you have a `requirements.txt` file with your PyPI dependencies.
 
 For more details information about configuring `rules_python`, see:
-* [Configuring the runtime](toolchains)
+* [Configuring the runtime](configuring-toolchains)
 * [Configuring third party dependencies (pip/pypi)](pypi-dependencies)
 * [API docs](api/index)
 

docs/index.md

@@ -101,8 +101,10 @@ pip
 coverage
 precompiling
 gazelle
+REPL <repl>
 Extending <extending>
 Contributing <contributing>
+devguide
 support
 Changelog <changelog>
 api/index

docs/repl.md

@@ -0,0 +1,66 @@
+# Getting a REPL or Interactive Shell
+
+rules_python provides a REPL to help with debugging and developing. The goal of
+the REPL is to present an environment identical to what a {bzl:obj}`py_binary` creates
+for your code.
+
+## Usage
+
+Start the REPL with the following command:
+```console
+$ bazel run @rules_python//python/bin:repl
+Python 3.11.11 (main, Mar 17 2025, 21:02:09) [Clang 20.1.0 ] on linux
+Type "help", "copyright", "credits" or "license" for more information.
+>>>
+```
+
+Settings like `//python/config_settings:python_version` will influence the exact
+behaviour.
+```console
+$ bazel run @rules_python//python/bin:repl --@rules_python//python/config_settings:python_version=3.13
+Python 3.13.2 (main, Mar 17 2025, 21:02:54) [Clang 20.1.0 ] on linux
+Type "help", "copyright", "credits" or "license" for more information.
+>>>
+```
+
+See [//python/config_settings](api/rules_python/python/config_settings/index)
+and [Environment Variables](environment-variables) for more settings.
+
+## Importing Python targets
+
+The `//python/bin:repl_dep` command line flag gives the REPL access to a target
+that provides the {bzl:obj}`PyInfo` provider.
+
+```console
+$ bazel run @rules_python//python/bin:repl --@rules_python//python/bin:repl_dep=@rules_python//tools:wheelmaker
+Python 3.11.11 (main, Mar 17 2025, 21:02:09) [Clang 20.1.0 ] on linux
+Type "help", "copyright", "credits" or "license" for more information.
+>>> import tools.wheelmaker
+>>>
+```
+
+## Customizing the shell
+
+By default, the `//python/bin:repl` target will invoke the shell from the `code`
+module. It's possible to switch to another shell by writing a custom "stub" and
+pointing the target at the necessary dependencies.
+
+### IPython Example
+
+For an IPython shell, create a file as follows.
+
+```python
+import IPython
+IPython.start_ipython()
+```
+
+Assuming the file is called `ipython_stub.py` and the `pip.parse` hub's name is
+`my_deps`, set this up in the .bazelrc file:
+```
+# Allow the REPL stub to import ipython. In this case, @my_deps is the hub name
+# of the pip.parse() call.
+build --@rules_python//python/bin:repl_stub_dep=@my_deps//ipython
+
+# Point the REPL at the stub created above.
+build --@rules_python//python/bin:repl_stub=//path/to:ipython_stub.py
+```