From 66a8b5b595710bd107c31ad5d449593536effb76 Mon Sep 17 00:00:00 2001
From: Ignas Anikevicius <240938+aignas@users.noreply.github.com>
Date: Thu, 19 Dec 2024 09:27:17 +0900
Subject: [PATCH] doc: correct toolchain usage in repository_rule context docs
 (#2510)

This clarifies a few points about how to use the python interpreter in
the repository
context. It also fixes outdated documentation as noted by some users of
1.0.

See discussion:
https://github.com/bazelbuild/rules_python/discussions/2509

Fixes #2494

---------

Co-authored-by: Richard Levasseur <richardlev@gmail.com>
---
 docs/toolchains.md                    | 41 +++++++++++++++++++++++++--
 examples/pip_parse_vendored/README.md |  3 +-
 2 files changed, 39 insertions(+), 5 deletions(-)

diff --git a/docs/toolchains.md b/docs/toolchains.md
index 4cc0948a8b..2a59169752 100644
--- a/docs/toolchains.md
+++ b/docs/toolchains.md
@@ -184,6 +184,43 @@ existing attributes:
 * Adding additional Python versions via {bzl:obj}`python.single_version_override` or
   {bzl:obj}`python.single_version_platform_override`.
 
+### Using defined toolchains from WORKSPACE
+
+It is possible to use toolchains defined in `MODULE.bazel` in `WORKSPACE`. For example
+the following `MODULE.bazel` and `WORKSPACE` provides a working {bzl:obj}`pip_parse` setup:
+```starlark
+# File: WORKSPACE
+load("@rules_python//python:repositories.bzl", "py_repositories")
+
+py_repositories()
+
+load("@rules_python//python:pip.bzl", "pip_parse")
+
+pip_parse(
+    name = "third_party",
+    requirements_lock = "//:requirements.txt",
+    python_interpreter_target = "@python_3_10_host//:python",
+)
+
+load("@third_party//:requirements.bzl", "install_deps")
+
+install_deps()
+
+# File: MODULE.bazel
+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")
+
+use_repo(python, "python_3_10", "python_3_10_host")
+```
+
+Note, the user has to import the `*_host` repository to use the python interpreter in the
+{bzl:obj}`pip_parse` and {bzl:obj}`whl_library` repository rules and once that is done
+users should be able to ensure the setting of the default toolchain even during the
+transition period when some of the code is still defined in `WORKSPACE`.
+
 ## Workspace configuration
 
 To import rules_python in your project, you first need to add it to your
@@ -229,13 +266,11 @@ python_register_toolchains(
     python_version = "3.11",
 )
 
-load("@python_3_11//:defs.bzl", "interpreter")
-
 load("@rules_python//python:pip.bzl", "pip_parse")
 
 pip_parse(
     ...
-    python_interpreter_target = interpreter,
+    python_interpreter_target = "@python_3_11_host//:python",
     ...
 )
 ```
diff --git a/examples/pip_parse_vendored/README.md b/examples/pip_parse_vendored/README.md
index f53260a175..fdf040c8e5 100644
--- a/examples/pip_parse_vendored/README.md
+++ b/examples/pip_parse_vendored/README.md
@@ -20,12 +20,11 @@ python_register_toolchains(
     name = "python39",
     python_version = "3.9",
 )
-load("@python39//:defs.bzl", "interpreter")
 
 # Load dependencies vendored by some other ruleset.
 load("@some_rules//:py_deps.bzl", "install_deps")
 
 install_deps(
-    python_interpreter_target = interpreter,
+    python_interpreter_target = "@python39_host//:python",
 )
 ```