//python/private/pypi:whl_library.bzl

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

  InWORKSPACE 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 isnot supported inMODULE.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)(defaultFalse)

  If true, add the lib dir of the bundled interpreter to the library search path viaLDFLAGS.

  Added in version 1.3.0.

  optional

• annotation –(label)(defaultNone)

  Optional json encoded file containing annotation to apply to the extracted wheel. Seepackage_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 whengenerating the authorization header for the http request. This enables the use of customauthorization 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 valuein the netrc file for the same host name. After formatting, the result is setas the value for theAuthorization 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 nameand the target that we need respectively.

  For example if your whl depends onnumpy and your Python package repo is namedpip so that you would normally do@pip//numpy, then this should be:@pip//{name}.

  optional

• download_only –(bool)(defaultFalse)

  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 differentplatform from the host platform.

  optional

• enable_implicit_namespace_pkgs –(bool)(defaultFalse)

  If true, disables conversion of native namespace packages into pkg-util style namespace packages. When set all py_binaryand py_test targets must specify eitherlegacy_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 ashttp_proxy,https_proxy andno_proxyNote that pip is run with “–isolated” on the CLI soPIP_<VAR>_<NAME>style env vars are ignored, but env vars that control requests and urllib3can be passed. If you needPIP_<VAR>_<NAME>, take a look atextra_pip_argsandenvsubst.

  optional

• envsubst –(list[str])(default[])

  A list of environment variables to substitute (e.g.["PIP_INDEX_URL","PIP_RETRIES"]). The corresponding variables are expanded inextra_pip_argsusing the syntax$VARNAME or${VARNAME} (expanding to empty string if unset)or${VARNAME:-default} (expanding to default if the variable is unset or emptyin the environment). Note: On Bazel 6 and Bazel 7.0 changes to the variables namedhere do not cause packages to be re-fetched. Don’t fetch different things basedon 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 asdependencies together in order to ensure that the cycle is always satisified.

  Example:sphinx depends onsphinxcontrib-serializinghtmlWhen 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 becollapsed down to one. For instancea<->b anda<->c cannot be listedas two separate cycles.

  optional

• experimental_target_platforms –(list[str])(default[])

  NOTE: This will be removed in the next major version, so please consider migratingtobzlmod and rely onpip.parse.requirements_by_platform for this feature.

  A list of platforms that we will generate the conditional dependency graph forcross platform wheels by parsing the wheel metadata. This will generate thecorrect dependencies for packages likesphinx orpylint, which includecolorama when installed and used on Windows platforms.

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

  WARNING: It may not work as expected in cases where the python interpreterimplementation 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 oflinux,osx,windows and arch is one ofx86_64,x86_32,aarch64,s390x andppc64le.

  You can also target a specific Python version by usingcp3<minor_version>_<os>_<arch>.If multiple python versions are specified as target platforms, then select statementsof thelib andwhl targets will include usage of version aware toolchain configsettings 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 thewhl 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 whenpaired with thewhl_modifications.

  Added in version 0.38.0:Forpip.parse with bzlmod

  Added in version 1.0.0:Forpip_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 unsetor empty in the environment), if"VARNAME" is listed in theenvsubst attribute. See alsoenvsubst.

  optional

• filename –(str)(default“”)

  Download the whl file to this filename. Only used when theurls is passed. If not specified, will be auto-detected from theurls.

  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)(defaultTrue)

  Whether or not to pass the–isolated flag tothe underlying pip command. Alternatively, theRULES_PYTHON_PIP_ISOLATED environment variable can be usedto 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 nameof a binary found on the host’sPATH environment variable. If no value is setpython3 is defaulted for Unix systems andpython.exe for Windows.

  optional

• python_interpreter_target –(label)(defaultNone)

  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 invokepip using the same interpreter as your toolchain. If set, takes precedence overpython_interpreter. An example value: “@python3_x86_64-unknown-linux-gnu//:python”.

  optional

• quiet –(bool)(defaultTrue)

  If True, suppress printing stdout and stderr output to the terminal.

  If you would like to get more diagnostic output, setRULES_PYTHON_REPO_DEBUG=1orRULES_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 theurls is passed.

  optional

• timeout –(int)(default600)

  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 thisattr makesextra_pip_args anddownload_only ignored.

  optional

• whl_file –(label)(defaultNone)

  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 asjson.encode(struct([whls],patch_strip]),wherewhls is alist[str] of wheel filenames, andpatch_stripis 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 betterway 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