chore: cleanup exposed python_repository symbols and add docs (#2189)
The bazel inventory for this sphinxdocs is in #2188.
Removed the things that are definitely not used and the rest of the
symbols
can be left until we become bzlmod only - they do not require much
maintenance.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e468e2b..bd94003 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -56,9 +56,12 @@
or deriving a new one from the original.
* (py_wheel) Removed use of bash to avoid failures on Windows machines which do not
have it installed.
+* (docs) Automatically generated documentation for {bzl:obj}`python_register_toolchains`
+ and related symbols.
### Removed
-* Nothing yet
+* (toolchains): Removed accidentally exposed `http_archive` symbol from
+ `python/repositories.bzl`.
## [0.35.0] - 2024-08-15
diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel
index f7f226a..e211c13 100644
--- a/docs/BUILD.bazel
+++ b/docs/BUILD.bazel
@@ -89,6 +89,7 @@
"//python:py_runtime_bzl",
"//python:py_runtime_info_bzl",
"//python:py_test_bzl",
+ "//python:repositories_bzl",
"//python/cc:py_cc_toolchain_info_bzl",
"//python/entry_points:py_console_script_binary_bzl",
"//python/private:py_exec_tools_info_bzl",
diff --git a/examples/bzlmod/MODULE.bazel.lock b/examples/bzlmod/MODULE.bazel.lock
index 8d02256..df0c96d 100644
--- a/examples/bzlmod/MODULE.bazel.lock
+++ b/examples/bzlmod/MODULE.bazel.lock
@@ -1231,7 +1231,7 @@
},
"@@rules_python~//python/extensions:pip.bzl%pip": {
"general": {
- "bzlTransitiveDigest": "9hiLCuWaaaU7Q+l2ONVr1A0NcG1JfSihv1UYeA1SpNY=",
+ "bzlTransitiveDigest": "NoDlhLqt5TG5tTcsLeBN6mnecYE+w8R4pvOKOF0ctC4=",
"usagesDigest": "MChlcSw99EuW3K7OOoMcXQIdcJnEh6YmfyjJm+9mxIg=",
"recordedFileInputs": {
"@@other_module~//requirements_lock_3_11.txt": "a7d0061366569043d5efcf80e34a32c732679367cb3c831c4cdc606adc36d314",
@@ -6140,7 +6140,7 @@
},
"@@rules_python~//python/private/pypi:pip.bzl%pip_internal": {
"general": {
- "bzlTransitiveDigest": "VoK/T0JkBdcomCHnDIYkX+stkywdxrh1MVM16e8D4sE=",
+ "bzlTransitiveDigest": "sh8kec0fTFOgrFmLOXLvQRfq+2g3Uv7rF0gj5xqnzKQ=",
"usagesDigest": "Y8ihY+R57BAFhalrVLVdJFrpwlbsiKz9JPJ99ljF7HA=",
"recordedFileInputs": {
"@@rules_python~//tools/publish/requirements.txt": "031e35d03dde03ae6305fe4b3d1f58ad7bdad857379752deede0f93649991b8a",
diff --git a/python/private/BUILD.bazel b/python/private/BUILD.bazel
index 8ddcc09..252606c 100644
--- a/python/private/BUILD.bazel
+++ b/python/private/BUILD.bazel
@@ -310,6 +310,7 @@
srcs = ["toolchains_repo.bzl"],
deps = [
":repo_utils_bzl",
+ ":text_util_bzl",
"//python:versions_bzl",
],
)
diff --git a/python/private/python_repositories.bzl b/python/private/python_repositories.bzl
index 25d8a96..8675399 100644
--- a/python/private/python_repositories.bzl
+++ b/python/private/python_repositories.bzl
@@ -80,12 +80,12 @@
"""Query a python interpreter target for whether or not it's a rules_rust provided toolchain
Args:
- rctx (repository_ctx): The repository rule's context object.
- python_interpreter_path (path): A path representing the interpreter.
+ rctx: {type}`repository_ctx` The repository rule's context object.
+ python_interpreter_path: {type}`path` A path representing the interpreter.
logger: Optional logger to use for operations.
Returns:
- bool: Whether or not the target is from a rules_python generated toolchain.
+ {type}`bool` Whether or not the target is from a rules_python generated toolchain.
"""
# Only update the location when using a hermetic toolchain.
@@ -563,35 +563,35 @@
def python_register_toolchains(
name,
python_version,
- distutils = None,
- distutils_content = None,
register_toolchains = True,
register_coverage_tool = False,
set_python_version_constraint = False,
- tool_versions = TOOL_VERSIONS,
+ tool_versions = None,
**kwargs):
"""Convenience macro for users which does typical setup.
- - Create a repository for each built-in platform like "python_linux_amd64" -
+ - Create a repository for each built-in platform like "python_3_8_linux_amd64" -
this repository is lazily fetched when Python is needed for that platform.
- Create a repository exposing toolchains for each platform like
"python_platforms".
- Register a toolchain pointing at each platform.
+
Users can avoid this macro and do these steps themselves, if they want more
control.
- Args:
- name: base name for all created repos, like "python38".
- python_version: the Python version.
- distutils: see the distutils attribute in the python_repository repository rule.
- distutils_content: see the distutils_content attribute in the python_repository repository rule.
- register_toolchains: Whether or not to register the downloaded toolchains.
- register_coverage_tool: Whether or not to register the downloaded coverage tool to the toolchains.
- NOTE: Coverage support using the toolchain is only supported in Bazel 6 and higher.
- set_python_version_constraint: When set to true, target_compatible_with for the toolchains will include a version constraint.
- tool_versions: a dict containing a mapping of version with SHASUM and platform info. If not supplied, the defaults
- in python/versions.bzl will be used.
- **kwargs: passed to each python_repositories call.
+ Args:
+ name: {type}`str` base name for all created repos, e.g. "python_3_8".
+ python_version: {type}`str` the Python version.
+ register_toolchains: {type}`bool` Whether or not to register the downloaded toolchains.
+ register_coverage_tool: {type}`bool` Whether or not to register the
+ downloaded coverage tool to the toolchains.
+ set_python_version_constraint: {type}`bool` When set to `True`,
+ `target_compatible_with` for the toolchains will include a version
+ constraint.
+ tool_versions: {type}`dict` contains a mapping of version with SHASUM
+ and platform info. If not supplied, the defaults in
+ python/versions.bzl will be used.
+ **kwargs: passed to each {obj}`python_repository` call.
"""
if BZLMOD_ENABLED:
@@ -599,6 +599,7 @@
register_toolchains = False
base_url = kwargs.pop("base_url", DEFAULT_RELEASE_BASE_URL)
+ tool_versions = tool_versions or TOOL_VERSIONS
python_version = full_version(python_version)
@@ -656,8 +657,6 @@
python_version = python_version,
release_filename = release_filename,
urls = urls,
- distutils = distutils,
- distutils_content = distutils_content,
strip_prefix = strip_prefix,
coverage_tool = coverage_tool,
**kwargs
@@ -709,11 +708,11 @@
"""Convenience macro for registering multiple Python toolchains.
Args:
- name: base name for each name in python_register_toolchains call.
- python_versions: the Python version.
- default_version: the default Python version. If not set, the first version in
- python_versions is used.
- **kwargs: passed to each python_register_toolchains call.
+ name: {type}`str` base name for each name in {obj}`python_register_toolchains` call.
+ python_versions: {type}`list[str]` the Python versions.
+ default_version: {type}`str` the default Python version. If not set,
+ the first version in python_versions is used.
+ **kwargs: passed to each {obj}`python_register_toolchains` call.
"""
if len(python_versions) == 0:
fail("python_versions must not be empty")
diff --git a/python/repositories.bzl b/python/repositories.bzl
index cf87234..88c00e2 100644
--- a/python/repositories.bzl
+++ b/python/repositories.bzl
@@ -18,7 +18,6 @@
load(
"//python/private:python_repositories.bzl",
_STANDALONE_INTERPRETER_FILENAME = "STANDALONE_INTERPRETER_FILENAME",
- _http_archive = "http_archive",
_is_standalone_interpreter = "is_standalone_interpreter",
_py_repositories = "py_repositories",
_python_register_multi_toolchains = "python_register_multi_toolchains",
@@ -30,9 +29,11 @@
python_register_multi_toolchains = _python_register_multi_toolchains
python_register_toolchains = _python_register_toolchains
+# Useful for documentation, but is not intended for public use - the python
+# module extension will be the main interface in the future.
+python_repository = _python_repository
+
# These symbols are of questionable public visibility. They were probably
# not intended to be actually public.
STANDALONE_INTERPRETER_FILENAME = _STANDALONE_INTERPRETER_FILENAME
-http_archive = _http_archive
is_standalone_interpreter = _is_standalone_interpreter
-python_repository = _python_repository
