Skip to content

docs: improve whl_library documentation #3266

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Sep 11, 2025
Merged

docs: improve whl_library documentation #3266

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b9d4002
update documentation
baxelrod-bdai Sep 11, 2025
ff9b5bb
expand doc description of data type
rickeylev Sep 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 26 additions & 5 deletions python/private/pypi/whl_library.bzl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -577,6 +577,9 @@ whl_library_attrs = dict({
The dep template to use for referencing the dependencies. It should have `{name}`
and `{target}` tokens that will be replaced with the normalized distribution name
and the target that we need respectively.

For example if your whl depends on `numpy` and your Python package repo is named
`pip` so that you would normally do `@pip//numpy`, then this should be: `@pip//{name}`.
Comment on lines +581 to +582
Copy link
Contributor

@gemini-code-assist gemini-code-assist bot Sep 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

This example is helpful for understanding the intent, but the suggested template @pip//{name} is inconsistent with the documentation above which states that the {target} token is also available. More importantly, this template will cause a failure when whl_library tries to load config.bzl from the repository. The implementation formats the template with target="config.bzl" and name="", which with the suggested template results in an invalid label @pip// for a load statement.

This indicates a potential issue in how dep_template is handled. To make the documentation correct and avoid confusing users, perhaps the example could be clarified that it's a simplified case and may not work universally. A more robust template would need to handle the {target} token, for instance: @pip//:{target}.

""",
),
"filename": attr.string(
Expand Down Expand Up @@ -615,11 +618,29 @@ attr makes `extra_pip_args` and `download_only` ignored.""",
doc = "The whl file that should be used instead of downloading or building the whl.",
),
"whl_patches": attr.label_keyed_string_dict(
doc = """a label-keyed-string dict that has
json.encode(struct([whl_file], patch_strip]) as values. This
is to maintain flexibility and correct bzlmod extension interface
until we have a better way to define whl_library and move whl
patching to a separate place. INTERNAL USE ONLY.""",
doc = """
A label-keyed-string dict with patch files as keys and json-strings as values.

The keys are labels to the patch file to apply.

The values describe what to apply the patch to and how to apply it.
It is encoded as `json.encode(struct([whls], patch_strip])`,
where `whls` is a `list[str`] of wheel filenames, and `patch_strip`
is a number.

So it will look something like this:
```
"//path/to/package:my.patch": json.encode(struct(
whls = ["something-2.7.1-py3-none-any.whl"],
patch_strip = 1,
)),
```
The patch is applied within the scope of the .whl file.
I.e. you should create the patch from the same place you unziped the wheel.


This is to maintain flexibility and correct bzlmod extension interface until we have a better
way to define whl_library and move whl patching to a separate place. INTERNAL USE ONLY.""",
),
"_python_path_entries": attr.label_list(
# Get the root directory of these rules and keep them as a default attribute
Expand Down