//python/extensions:python.bzl

Python toolchain module extensions for use with bzlmod.

Basic usage

The simplest way to configure the toolchain withrules_python is as follows.

python=use_extension("@rules_python//python/extensions:python.bzl","python")python.defaults(python_version="3.11")python.toolchain(python_version="3.11")use_repo(python,"python_3_11")

Overrides

Overrides can be done at 3 different levels:

See also

The main documentation page on registeringtoolchains.

moduleextpython

Bzlmod extension that is used to register Python toolchains.

python.defaults(python_version='',python_version_env='',python_version_file=None)

Tag class to specify the default Python version.

Attributes:

  • python_version –(str)(default“”)

    String saying what the default Python version should be. If the stringmatches thepython_version attribute of a toolchain, thistoolchain is the default version. If this attribute is set, theis_default attribute of the toolchain is ignored.

    Added in version 1.4.0.

    optional

  • python_version_env –(str)(default“”)

    Environment variable saying what the default Python version should be.If the string matches thepython_version attribute of atoolchain, this toolchain is the default version. If this attribute isset, theis_default attribute of the toolchain is ignored.

    Added in version 1.4.0.

    optional

  • python_version_file –(label)(defaultNone)

    File saying what the default Python version should be. If the contentsof the file match thepython_version attribute of a toolchain,this toolchain is the default version. If this attribute is set, theis_default attribute of the toolchain is ignored.

    Added in version 1.4.0.

    optional

python.override(auth_patterns={},available_python_versions=[],base_url='https://github.com/astral-sh/python-build-standalone/releases/download',ignore_root_user_error=True,minor_mapping={},netrc='',register_all_versions=False)

Tag class used to override defaults and behaviour of the module extension.

Added in version 0.36.0.

Attributes:

  • 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

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

    The list of available python tool versions to use. Must be inX.Y.Z format.If the unknown version given the processing of the extension will fail - all ofthe versions in the list have to be defined withpython.single_version_override orpython.single_version_platform_override before they are used in thislist.

    This attribute is usually used in order to ensure that no unexpected transitivedependencies are introduced.

    optional

  • base_url –(str)(default“https://github.com/astral-sh/python-build-standalone/releases/download”)

    The base URL to be used when downloading toolchains.

    optional

  • ignore_root_user_error –(bool)(defaultTrue)

    Deprecated; do not use. This attribute has no effect.

    optional

  • minor_mapping –(dict[str,str])(default{})

    The mapping betweenX.Y toX.Y.Z versions to be used when setting uptoolchains. It defaults to the interpreter with the highest available patchversion for each minor version. For example if one registers3.10.3,3.10.4and3.11.4 then the default for theminor_mapping dict will be:

    {"3.10":"3.10.4","3.11":"3.11.4",}

    Changed in version 0.37.0:The values in this mapping override the default values and do not replace them.

    optional

  • netrc –(str)(default“”)

    Location of the .netrc file to use for authentication

    optional

  • register_all_versions –(bool)(defaultFalse)

    Add all versions

    optional

python.single_version_override(python_version,distutils=None,distutils_content='',patch_strip=0,patches=[],sha256={},strip_prefix='python',urls=[])

Override single python version URLs and patches for all platforms.

Note

This will replace any existing configuration for the given python version.

Tip

If you would like to modify the configuration for a specific(version,platform), please use thesingle_version_platform_override tagclass.

Added in version 0.36.0.

Attributes:
python.single_version_platform_override(platform,python_version,arch='',coverage_tool=None,os_name='',patch_strip=0,patches=[],sha256='',strip_prefix='python',target_compatible_with=[],target_settings=[],urls=[])

Override single python version for a single existing platform.

If the(version,platform) is new, we will add it to the existing versions and willuse the sameurl template.

Tip

If you would like to add or remove platforms to a single python version toolchainconfiguration, please usesingle_version_override.

Added in version 0.36.0.

Attributes:

  • platform –(str)

    The platform to override the values for, typically one of:

    • aarch64-apple-darwin-freethreaded

    • aarch64-apple-darwin

    • aarch64-pc-windows-msvc-freethreaded

    • aarch64-pc-windows-msvc

    • aarch64-unknown-linux-gnu-freethreaded

    • aarch64-unknown-linux-gnu

    • armv7-unknown-linux-gnu-freethreaded

    • armv7-unknown-linux-gnu

    • i386-unknown-linux-gnu-freethreaded

    • i386-unknown-linux-gnu

    • ppc64le-unknown-linux-gnu-freethreaded

    • ppc64le-unknown-linux-gnu

    • riscv64-unknown-linux-gnu-freethreaded

    • riscv64-unknown-linux-gnu

    • s390x-unknown-linux-gnu-freethreaded

    • s390x-unknown-linux-gnu

    • x86_64-apple-darwin-freethreaded

    • x86_64-apple-darwin

    • x86_64-pc-windows-msvc-freethreaded

    • x86_64-pc-windows-msvc

    • x86_64-unknown-linux-gnu-freethreaded

    • x86_64-unknown-linux-gnu

    • x86_64-unknown-linux-musl-freethreaded

    • x86_64-unknown-linux-musl

    Other values are allowed, in which case,target_compatible_with,target_settings,os_name, andarch should be specified so the toolchain isonly used when appropriate.

    Changed in version 1.5.0:Arbitrary platform strings allowed.

    mandatory

  • python_version –(str)

    The python version to override URLs for. Must be inX.Y.Z format.

    mandatory

  • arch –(str)(default“”)

    The arch (cpu) the runtime is compatible with.

    If not set, then the runtime cannot be used as apython_X_Y_host runtime.

    If set, theos_name,target_compatible_with andtarget_settings attributesshould also be set.

    The values should be one of the values in@platforms//cpu

    See also

    Docs for [Registering custom runtimes]

    optional

  • coverage_tool –(label)(defaultNone)

    The coverage tool to be used for a particular Python interpreter. This can overriderules_python defaults.

    optional

  • os_name –(str)(default“”)

    The host OS the runtime is compatible with.

    If not set, then the runtime cannot be used as apython_X_Y_host runtime.

    If set, theos_name,target_compatible_with andtarget_settings attributesshould also be set.

    The values should be one of the values in@platforms//os

    See also

    Docs for [Registering custom runtimes]

    optional

  • patch_strip –(int)(default0)

    Same as the –strip argument of Unix patch.

    optional

  • patches –(list[label])(default[])

    A list of labels pointing to patch files to apply for the interpreter repository. They are applied in the list order and are applied after the common patches are applied.

    optional

  • sha256 –(str)(default“”)

    The sha256 for the archive

    optional

  • strip_prefix –(str)(default“python”)

    The ‘strip_prefix’ for the archive, defaults to ‘python’.

    optional

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

    Thetarget_compatible_with values to use for the toolchain definition.

    If not set, thenos_name andarch will be used to populate it.

    If set,target_settings,os_name, andarch should also be set.

    See also

    Docs for [Registering custom runtimes]

    optional

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

    Thetarget_setings values to use for the toolchain definition.

    If set,target_compatible_with,os_name, andarch should also be set.

    See also

    Docs for [Registering custom runtimes]

    optional

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

    The URL template to fetch releases for this Python version. If the URL template results in a relative fragment, default base URL is going to be used. Occurrences of{python_version},{platform} and{build} will be interpolated based on the contents in the override and the knownplatform values.

    optional

python.toolchain(python_version,configure_coverage_tool=False,ignore_root_user_error=True,is_default=False)

Tag class used to register Python toolchains.Use this tag class to register one or more Python toolchains. This classis also potentially called by sub modules. The following covers differentbusiness rules and use cases.

Toolchains in the Root Module

This class registers all toolchains in the root module.

Toolchains in Sub Modules

It will create a toolchain that is in a sub module, if the toolchainof the same name does not exist in the root module. The extension stops nameclashing between toolchains in the root module and toolchains in 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 that exists in a sub module,if the sub module toolchain is marked as the default version. If you havemore than one toolchain in your root module, you need to set one of thetoolchains as the default version. If there is only one toolchain itis set as the default toolchain.

Toolchain repository name

A toolchain’s repository name uses the formatpython_{major}_{minor}, e.g.python_3_10. Themajor andminor components aremajor andminor are the Python version from thepython_version attribute.

If a toolchain is registered inX.Y.Z, then similarly the toolchain name willbepython_{major}_{minor}_{patch}, e.g.python_3_10_19.

Toolchain detection

The definition of the first toolchain wins, which means that the root modulecan override settings for any python toolchain available. This relies on thedocumented module traversal from themodule_ctx.modules.

Tip

In order to use a different name than the above, you can use the followingMODULE.bazelsyntax:

python=use_extension("@rules_python//python/extensions:python.bzl","python")python.defaults(python_version="3.11")python.toolchain(python_version="3.11")use_repo(python,my_python_name="python_3_11")

Then the python interpreter will be available asmy_python_name.

Attributes:

  • python_version –(str)

    The Python version, inmajor.minor ormajor.minor.patch format, e.g3.12 (or3.12.3), to create a toolchain for.

    mandatory

  • configure_coverage_tool –(bool)(defaultFalse)

    Whether or not to configure the default coverage tool provided byrules_python for the compatible toolchains.

    optional

  • ignore_root_user_error –(bool)(defaultTrue)

    Changed in version VERSION_NEXT_FEATURE:Noop, will be removed in the next major release.

    optional

  • is_default –(bool)(defaultFalse)

    Whether the toolchain is the default version.

    Changed in version 1.4.0:This setting is ignored if the default version is set using thedefaultstag class (encouraged).

    optional