We do this work for two reasons.

First, we must support Module dependencies and sub-modules using
`python.toolchain`. There are already two known instances of sub-modules
setting up a Python toolchain and colliding with another module
(nanobind and rules_testing both run into this).

Second, the upcoming multi-version support is going to work by having
each `python.toolchain()` call register its particular version with the
extra toolchain constraint. This also helps unify the version-aware and
non-version-aware code paths (the non-version aware paths are just
version-aware with a single version registered as the default)

This commit implements various business logic in the toolchain class.

Toolchains in Sub Modules

It will create a toolchain in a sub-module if the toolchain
of the same name does not exist in the root module. The extension stops
name
clashing between toolchains in the root module and sub-modules.
You cannot configure more than one toolchain as the default toolchain.

Toolchain set as the default version.

This extension will not create a toolchain in a sub-module
if the sub-module toolchain is marked as the default version. If you
have
more than one toolchain in your root module, you need to set one of the
toolchains as the default version.  If there is only one toolchain, it
is set as the default toolchain.

See #1229 for more information

Gazelle v0.31.0 comes with a lifecycle manager for extension, allowing
the Python extension to properly shut down external Python processes
without relying on timer.

Upgrading Gazelle in this PR. Using the lifecycle manager will come
next.

…mport_all_repositories=false` (#1243)

Because `--experimental_python_import_all_repositories` defaults to
true, every repository's directory is added to `sys.path`, which makes
`import python.runfiles` work.

However, we shouldn't rely on that behavior for a couple reasons:
* We recommend disabling it for fewer sys.path entries (even non-Python
related
    repos get added to the path).
* Some users _must_ disable it because the resulting PYTHONPATH is too
long.

To fix, set the `imports` attribute on `//python/runfiles:runfiles` so
that `import python.runfiles` works. The net result is the
`rules_python` repo directory is added
to sys.path even if
`--experimental_python_import_all_repositories=false`.

Fixes #1241

This commit moves the register.toolchains bzlmod call to inside
of rules_python.  Instead of a user having to call register.toolchains
in their MODULE.bazel, rules_python/MODULE.bazel calls it
on the internal hub.

This is a breaking change if you are using register.toolchains inside
of submodules.  Using register.toolchains inside of submodules is
not recommended anyways.  This is now broken because we are not
creating a repo for every Python version toolchain.  All of the
toochain calls exist now in the hub's repo BUILD.bazel file.

The documentation is currently ambiguous on whether or not to check
requirements.txt into version control. This has raised some confusion in
other projects (e.g., google/gematria#3). This
makes it clear that requirements.txt files produced by this rule should
be checked into version control in an easy to find place to avoid
confusion.

…ternary (#1246)

The generated toolchain BUILD file is confusing to read because it
relies on a ternary expression in the BUILD file to set the
`target_settings` attribute. This makes debugging harder because, upon
first look, all the toolchains appear to have the version constraint
set. It's only upon closer inspection that you can see the 1-character
difference of "False" vs "True" embedded into the middle of a line
amongst other similar looking lines.

Also:
* Adds a bit of validation logic for the `set_python_version_constraint`
argument
because it's conceptually a boolean, but is passed as a string, so is
prone to
    having an incorrect value passed.
* Documents the `set_python_version_constraint` arg, since it has a
particular range
    of values it accepts.

…1244)

This fixes an issue where the last submodule, instead of the first, was
given precedence when creating versioned toolchains. To fix, when
creating the map of versioned toolchains, if a version is already
defined, then a subsequent usage is ignored. A warning is emitted when
this occurs.

This also fixes a similar problem that can occur to the root module. If
the root module uses a particular version marked as the default, and is
using the versioned rules, and a submodule also uses that same version,
then the submodule's toolchain would be used. This happened because the
root module's toolchain would be moved last, so its versioned rules
would match the submodule's versioned toolchain.

This also does some cleanup and refactoring to:
  * Compute the toolchains in one loop iteration
  * Give more informative error messages
* Reject duplicate names within a module, even for the non-root module.
  * Reject duplicate versions within a module.

Currently the users need to run the script manually and this PR adds a
pre-commit hook which should facilitate the maintenance of the deleted
packages within the `rules_python .bazelrc`.

…1249)

Fixes #1196.

Currently the `coverage.py` module does not work if updated to the
latest
version with the following error:
```
ImportError: cannot import name 'MappingProxyType' from partially
initialized module 'types' (most likely due to a circular import)
...~pypi__coverage_cp39_x86_64-unknown-linux-gnu/coverage/types.py)
```

Where the `MappingProxyType` actually exists in Python's std lib. To
fix,
modify sys.path before the first import of coverage.

Summary:
- chore(coverage): bump coverage.py to 7.2.7
- fix(coverage): patch sys.path before importing anything from coverage
- test(coverage): add extra assertions about the module names

…uild-standalone (#1234)

This is being added in order to once again be able to build envoyproxy
on the `ppc64le` architecture.

Little Endian Power support was added to release
https://github.com/indygreg/python-build-standalone/releases/tag/20230507.

Signed-off-by: Christy Norman <christy@linux.vnet.ibm.com>

The main reasons this is removed is because if modules choose different
names for the same toolchain, only one of the two toolchains (which are,
hopefully, identical) will be used. Which toolchain is used depends on
the module graph dependency ordering.

Furthermore, as of #1238, only one repo per version is created; others
are ignored. This means a module doesn't know if the name it chooses
will result in a repo being created with that name.

Instead, the toolchain repos are named by rules_python:
`python_{major}_{minor}`. These repo names are currently part of the
public API, since they end up referenced in MODULE config (to wire the
toolchain interpreter to pip).

BREAKING CHANGES

This removes the `name` arg from `python.toolchain()`. Users will need
to remove such usages from their `MODULE.bazel` and update their
`use_repo()` statements. If keeping the custom repo name is necessary,
then repo mappings can be used. See #1232 for additional migration
steps, commands, and information.

…k files (#1123)

Currently the dependency_resolver.py ignores that you give requirement
lock files for different os's, except when checking if the golden file
needs updating. This causes dependecy_resolver.py to update the wrong
lock i.e the non platform specific one if ran in "update mode".

[`wheel_installer` assumes that if the pip command succeeded, there must
be at least one `*.whl`
file](https://github.com/lpulley/rules_python/blob/fdec44120aa45d748ab804f1d019002c6949b449/python/pip_install/tools/wheel_installer/wheel_installer.py#L439),
but this is not currently true when `download_only` is enabled and the
package provides no wheel; a `.tar.gz` will happily be downloaded, pip
will succeed, and the `next(iter(glob.glob("*.whl")))` call will fail,
producing a mysterious `StopIteration`:

```
Saved ./artifactory-0.1.17.tar.gz
Successfully downloaded artifactory
 (Traceback (most recent call last):
  File "[redacted]/lib/python3.8/runpy.py", line 194, in _run_module_as_main
    return _run_code(code, main_globals, None,
  File "[redacted]/lib/python3.8/runpy.py", line 87, in _run_code
    exec(code, run_globals)
  File "[redacted]/external/rules_python/python/pip_install/tools/wheel_installer/wheel_installer.py", line 450, in <module>
    main()
  File "[redacted]/external/rules_python/python/pip_install/tools/wheel_installer/wheel_installer.py", line 438, in main
    whl = next(iter(glob.glob("*.whl")))
StopIteration
)
```

By using `--only-binary=:all:` when using `pip download`, the pip
command will fail if there is no suitable wheel to be downloaded. This
should make the error much more obvious, since with
`--only-binary=:all:` and no suitable wheel, pip fails and reports an
error like this:

```
ERROR: Could not find a version that satisfies the requirement artifactory (from versions: none)
ERROR: No matching distribution found for artifactory
```

This allows the `distribution` attribute to expand workspace status
keys, just as the
`version` attribute can.

This allows, for example, the VCS's branch name (e.g test, release, etc)
to be part of the
distribution name without having to modify the BUILD file. Having
distinct distribution
names is necessary because tools like pip-compile, which determine
version compatibility
and replacements, and having the same distribution name would mean the
different builds
are seen as equivalent.

Closes #1250

This makes rules_python always provide a default toolchain when using
bzlmod.

Note that, unlike workspace builds, the default is not the local
system Python (`@bazel_tools//tools/python:autodetecting_toolchain`).

Instead, the default is a hermetic runtime, but no guarantees are made
about the particular version used. In practice, it will be the latest
available Python version.

Work towards #1233