From 4d6981451285102c88839b313e83a0530461505f Mon Sep 17 00:00:00 2001
From: Alex Eagle <alex@aspect.dev>
Date: Tue, 8 Mar 2022 06:24:45 -0800
Subject: [PATCH 1/2] Minor code review suggestions

---
 README.md                          | 13 +++++++------
 WORKSPACE                          |  1 +
 python/private/toolchains_repo.bzl |  3 ++-
 python/versions.bzl                |  1 +
 4 files changed, 11 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 7d2699af38..e710bdb154 100644
--- a/README.md
+++ b/README.md
@@ -54,16 +54,14 @@ http_archive(
 )
 ```
 
-To register a hermetic Python toolchain (please refer to
-[this link](https://python-build-standalone.readthedocs.io/en/latest/quirks.html) for the list of
-quirks you may find while using the toolchain), you can add to the `WORKSPACE` file:
+To register a hermetic Python toolchain rather than rely on whatever is already on the machine, you can add to the `WORKSPACE` file:
 
 ```python
 load("@rules_python//python:repositories.bzl", "python_register_toolchains")
 
-# Multiple versions are available in the @rules_python//python:versions.bzl file.
 python_register_toolchains(
     name = "python310",
+    # Available versions are listed in @rules_python//python:versions.bzl
     python_version = "3.10",
 )
 
@@ -78,6 +76,9 @@ pip_parse(
 )
 ```
 
+> You may find some quirks while using this toolchain.
+> Please refer to [this link](https://python-build-standalone.readthedocs.io/en/latest/quirks.html) for details.
+
 Once you've imported the rule set into your `WORKSPACE` using any of these
 methods, you can then load the core rules in your `BUILD` files with:
 
@@ -133,8 +134,8 @@ one another, and may result in downloading the same wheels multiple times.
 
 As with any repository rule, if you would like to ensure that `pip_install` is
 re-executed in order to pick up a non-hermetic change to your environment (e.g.,
-updating your system `python` interpreter), you can completely flush out your
-repo cache with `bazel clean --expunge`.
+updating your system `python` interpreter), you can force it to re-execute by running
+`bazel sync --only [pip_install name]`
 
 ### Fetch `pip` dependencies lazily
 
diff --git a/WORKSPACE b/WORKSPACE
index 09319adad0..b43a8d8e1d 100644
--- a/WORKSPACE
+++ b/WORKSPACE
@@ -30,6 +30,7 @@ load("//python:versions.bzl", "MINOR_MAPPING")
 
 python_register_toolchains(
     name = "python",
+    # We always use the latest Python internally.
     python_version = MINOR_MAPPING.values()[-1],
 )
 
diff --git a/python/private/toolchains_repo.bzl b/python/private/toolchains_repo.bzl
index 6044bf8300..e171e43a1e 100644
--- a/python/private/toolchains_repo.bzl
+++ b/python/private/toolchains_repo.bzl
@@ -44,10 +44,11 @@ def _toolchains_repo_impl(rctx):
 
     for [platform, meta] in PLATFORMS.items():
         build_content += """\
+# Bazel selects this toolchain to get a Python interpreter
+# for executing build actions.
 toolchain(
     name = "{platform}_toolchain",
     exec_compatible_with = {compatible_with},
-    target_compatible_with = {compatible_with},
     toolchain = "@{user_repository_name}_{platform}//:python_runtimes",
     toolchain_type = "@bazel_tools//tools/python:toolchain_type",
 )
diff --git a/python/versions.bzl b/python/versions.bzl
index a61527cc1f..e29c4ba5d2 100644
--- a/python/versions.bzl
+++ b/python/versions.bzl
@@ -15,6 +15,7 @@
 """The Python versions we use for the toolchains.
 """
 
+# Values returned by https://bazel.build/rules/lib/repository_os
 MACOS_NAME = "mac os"
 LINUX_NAME = "linux"
 WINDOWS_NAME = "windows"

From 883246e022fe1f05acaf115d20c5a2029fecc0bb Mon Sep 17 00:00:00 2001
From: Thulio Ferraz Assis <3149049+f0rmiga@users.noreply.github.com>
Date: Tue, 8 Mar 2022 09:40:39 -0800
Subject: [PATCH 2/2] Apply suggestions from code review

---
 README.md           | 4 ++--
 python/versions.bzl | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index e710bdb154..5a22e8a8f7 100644
--- a/README.md
+++ b/README.md
@@ -61,7 +61,7 @@ load("@rules_python//python:repositories.bzl", "python_register_toolchains")
 
 python_register_toolchains(
     name = "python310",
-    # Available versions are listed in @rules_python//python:versions.bzl
+    # Available versions are listed in @rules_python//python:versions.bzl.
     python_version = "3.10",
 )
 
@@ -135,7 +135,7 @@ one another, and may result in downloading the same wheels multiple times.
 As with any repository rule, if you would like to ensure that `pip_install` is
 re-executed in order to pick up a non-hermetic change to your environment (e.g.,
 updating your system `python` interpreter), you can force it to re-execute by running
-`bazel sync --only [pip_install name]`
+`bazel sync --only [pip_install name]`.
 
 ### Fetch `pip` dependencies lazily
 
diff --git a/python/versions.bzl b/python/versions.bzl
index e29c4ba5d2..a99e371324 100644
--- a/python/versions.bzl
+++ b/python/versions.bzl
@@ -15,7 +15,7 @@
 """The Python versions we use for the toolchains.
 """
 
-# Values returned by https://bazel.build/rules/lib/repository_os
+# Values returned by https://bazel.build/rules/lib/repository_os.
 MACOS_NAME = "mac os"
 LINUX_NAME = "linux"
 WINDOWS_NAME = "windows"