Minor code review suggestions

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
 

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],
 )
 

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",
 )

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"