pypi:whl_library.bzl

repo rule whl_library(name, repo_mapping, requirement, add_libdir_to_library_search_path=False, annotation=None, auth_patterns={}, config_load='', dep_template='', download_only=False, enable_implicit_namespace_pkgs=False, environment={}, envsubst=[], experimental_requirement_cycles={}, experimental_target_platforms=[], extra_hub_aliases={}, extra_pip_args=[], filename='', group_deps=[], group_name='', isolated=True, netrc='', pip_data_exclude=[], python_interpreter='', python_interpreter_target=None, quiet=True, repo='', repo_prefix='', sha256='', timeout=600, urls=[], whl_file=None, whl_patches={})

Download and extracts a single wheel based into a bazel repo based on the requirement string passed in. Instantiated from pip_repository and inherits config options from there.

Attributes:

name – (Name)
A unique name for this repository.

mandatory
repo_mapping – (dict[str, str])
In WORKSPACE context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.

For example, an entry "@foo": "@bar" declares that, for any time this repository depends on @foo (such as a dependency on @foo//some:target, it should actually resolve that dependency within globally-declared @bar (@bar//some:target).

This attribute is not supported in MODULE.bazel context (when invoking a repository rule inside a module extension’s implementation function).

optional
requirement – (str)
Python requirement string describing the package to make available, if ‘urls’ or ‘whl_file’ is given, then this only needs to include foo[any_extras] as a bare minimum.

mandatory
add_libdir_to_library_search_path – (bool) (default False)
If true, add the lib dir of the bundled interpreter to the library search path via LDFLAGS.

Added in version 1.3.0.

optional
annotation – (label) (default None)
Optional json encoded file containing annotation to apply to the extracted wheel. See package_annotation

optional
auth_patterns – (dict[str, str]) (default {})
An optional dict mapping host names to custom authorization patterns.

If a URL’s host name is present in this dict the value will be used as a pattern when generating the authorization header for the http request. This enables the use of custom authorization schemes used in a lot of common cloud storage providers.

The pattern currently supports 2 tokens: <login> and <password>, which are replaced with their equivalent value in the netrc file for the same host name. After formatting, the result is set as the value for the Authorization field of the HTTP request.

Example attribute and netrc for a http download to an oauth2 enabled API using a bearer token:
```
auth_patterns = {
    "storage.cloudprovider.com": "Bearer <password>"
}
```
netrc:
```
machine storage.cloudprovider.com
        password RANDOM-TOKEN
```
The final HTTP request would have the following header:
```
Authorization: Bearer RANDOM-TOKEN
```
optional
config_load – (str) (default “”)
The load location for configuration for pipstar.

optional
dep_template – (str) (default “”)
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}.

optional
download_only – (bool) (default False)
Whether to use “pip download” instead of “pip wheel”. Disables building wheels from source, but allows use of –platform, –python-version, –implementation, and –abi in –extra_pip_args to download wheels for a different platform from the host platform.

optional
enable_implicit_namespace_pkgs – (bool) (default False)
If true, disables conversion of native namespace packages into pkg-util style namespace packages. When set all py_binary and py_test targets must specify either legacy_create_init=False or the global Bazel option --incompatible_default_to_explicit_init_py to prevent __init__.py being automatically generated in every directory.

This option is required to support some packages which cannot handle the conversion to pkg-util style.

optional
environment – (dict[str, str]) (default {})
Environment variables to set in the pip subprocess. Can be used to set common variables such as http_proxy, https_proxy and no_proxy Note that pip is run with “–isolated” on the CLI so PIP_<VAR>_<NAME> style env vars are ignored, but env vars that control requests and urllib3 can be passed. If you need PIP_<VAR>_<NAME>, take a look at extra_pip_args and envsubst.

optional
envsubst – (list[str]) (default [])
A list of environment variables to substitute (e.g. ["PIP_INDEX_URL", "PIP_RETRIES"]). The corresponding variables are expanded in extra_pip_args using the syntax $VARNAME or ${VARNAME} (expanding to empty string if unset) or ${VARNAME:-default} (expanding to default if the variable is unset or empty in the environment). Note: On Bazel 6 and Bazel 7.0 changes to the variables named here do not cause packages to be re-fetched. Don’t fetch different things based on the value of these variables.

optional

experimental_requirement_cycles – (dict[str, list[str]]) (default {})

A mapping of dependency cycle names to a list of requirements which form that cycle.

Requirements which form cycles will be installed together and taken as dependencies together in order to ensure that the cycle is always satisified.

Example: sphinx depends on sphinxcontrib-serializinghtml When listing both as requirements, ala

py_binary(
  name = "doctool",
  ...
  deps = [
    "@pypi//sphinx:pkg",
    "@pypi//sphinxcontrib_serializinghtml",
   ]
)

Will produce a Bazel error such as

ERROR: .../external/pypi_sphinxcontrib_serializinghtml/BUILD.bazel:44:6: in alias rule @pypi_sphinxcontrib_serializinghtml//:pkg: cycle in dependency graph:
    //:doctool (...)
    @pypi//sphinxcontrib_serializinghtml:pkg (...)
.-> @pypi_sphinxcontrib_serializinghtml//:pkg (...)
|   @pypi_sphinxcontrib_serializinghtml//:_pkg (...)
|   @pypi_sphinx//:pkg (...)
|   @pypi_sphinx//:_pkg (...)
`-- @pypi_sphinxcontrib_serializinghtml//:pkg (...)

Which we can resolve by configuring these two requirements to be installed together as a cycle

pip_parse(
  ...
  experimental_requirement_cycles = {
    "sphinx": [
      "sphinx",
      "sphinxcontrib-serializinghtml",
    ]
  },
)

Warning: If a dependency participates in multiple cycles, all of those cycles must be collapsed down to one. For instance a <-> b and a <-> c cannot be listed as two separate cycles.

optional

experimental_target_platforms – (list[str]) (default [])
NOTE: This will be removed in the next major version, so please consider migrating to bzlmod and rely on pip.parse.requirements_by_platform for this feature.

A list of platforms that we will generate the conditional dependency graph for cross platform wheels by parsing the wheel metadata. This will generate the correct dependencies for packages like sphinx or pylint, which include colorama when installed and used on Windows platforms.

An empty list means falling back to the legacy behaviour where the host platform is the target platform.

WARNING: It may not work as expected in cases where the python interpreter implementation that is being used at runtime is different between different platforms. This has been tested for CPython only.

For specific target platforms use values of the form <os>_<arch> where <os> is one of linux, osx, windows and arch is one of x86_64, x86_32, aarch64, s390x and ppc64le.

You can also target a specific Python version by using cp3<minor_version>_<os>_<arch>. If multiple python versions are specified as target platforms, then select statements of the lib and whl targets will include usage of version aware toolchain config settings like @rules_python//python/config_settings:is_python_3.y.

Special values: host (for generating deps for the host platform only) and <prefix>_* values. For example, cp39_*, linux_*, cp39_linux_*.

NOTE: this is not for cross-compiling Python wheels but rather for parsing the whl METADATA correctly.

optional
extra_hub_aliases – (dict[str, list[str]]) (default {})
Extra aliases to make for specific wheels in the hub repo. This is useful when paired with the whl_modifications.

Added in version 0.38.0: For pip.parse with bzlmod

Added in version 1.0.0: For pip_parse with workspace.

optional
extra_pip_args – (list[str]) (default [])
Extra arguments to pass on to pip. Must not contain spaces.

Supports environment variables using the syntax $VARNAME or ${VARNAME} (expanding to empty string if unset) or ${VARNAME:-default} (expanding to default if the variable is unset or empty in the environment), if "VARNAME" is listed in the envsubst attribute. See also envsubst.

optional
filename – (str) (default “”)
Download the whl file to this filename. Only used when the urls is passed. If not specified, will be auto-detected from the urls.

optional
group_deps – (list[str]) (default [])
List of dependencies to skip in order to break the cycles within a dependency group.

optional
group_name – (str) (default “”)
Name of the group, if any.

optional
isolated – (bool) (default True)
Whether or not to pass the –isolated flag to the underlying pip command. Alternatively, the RULES_PYTHON_PIP_ISOLATED environment variable can be used to control this flag.

optional
netrc – (str) (default “”)
Location of the .netrc file to use for authentication

optional
pip_data_exclude – (list[str]) (default [])
Additional data exclusion parameters to add to the pip packages BUILD file.

optional
python_interpreter – (str) (default “”)
The python interpreter to use. This can either be an absolute path or the name of a binary found on the host’s PATH environment variable. If no value is set python3 is defaulted for Unix systems and python.exe for Windows.

optional
python_interpreter_target – (label) (default None)
If you are using a custom python interpreter built by another repository rule, use this attribute to specify its BUILD target. This allows pip_repository to invoke pip using the same interpreter as your toolchain. If set, takes precedence over python_interpreter. An example value: “@python3_x86_64-unknown-linux-gnu//:python”.

optional
quiet – (bool) (default True)
If True, suppress printing stdout and stderr output to the terminal.

If you would like to get more diagnostic output, set RULES_PYTHON_REPO_DEBUG=1 or RULES_PYTHON_REPO_DEBUG_VERBOSITY=INFO|DEBUG|TRACE

optional
repo – (str) (default “”)
Pointer to parent repo name. Used to make these rules rerun if the parent repo changes.

optional
repo_prefix – (str) (default “”)
Prefix for the generated packages will be of the form @<prefix><sanitized-package-name>//...

DEPRECATED. Only left for people who vendor requirements.bzl.

optional
sha256 – (str) (default “”)
The sha256 of the downloaded whl. Only used when the urls is passed.

optional
timeout – (int) (default 600)
Timeout (in seconds) on the rule’s execution duration.

optional
urls – (list[str]) (default [])
The list of urls of the whl to be downloaded using bazel downloader. Using this attr makes extra_pip_args and download_only ignored.

optional
whl_file – (label) (default None)
The whl file that should be used instead of downloading or building the whl.

optional
whl_patches – (dict[label, str]) (default {})
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.

optional

Envvars:

RULES_PYTHON_PIP_ISOLATED, RULES_PYTHON_REPO_DEBUG