rules_pyo3

Bazel rules for PyO3.

These rules use the hermetic toolchain infrastructure from rules_python to build PyO3 extension modules to be as reproducible as possible.

Setup

In order to use rules_pyo3 it's recommended to first setup your rules_rust and rules_python.

Refer to their setup documentation for guidance:

bzlmod

bazel_dep(name = "rules_pyo3", version = "{SEE_RELEASES_PAGE}")

# Register default toolchains or customize your own.
register_toolchains(
    "@rules_pyo3//pyo3/toolchains:toolchain",
    "@rules_pyo3//pyo3/toolchains:rust_toolchain",
)

WORKSPACE

Once rules_rust and rules_python toolchains are all configured, the following snippet can be used to configure the necessary toolchains for PyO3:

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

http_archive(
    name = "rules_pyo3",
    #
    # TODO: See release page for integrity and url info:
    #
    # https://github.com/abrisco/rules_pyo3/releases
)

load("@rules_pyo3//pyo3:repositories.bzl", "register_pyo3_toolchains", "rules_pyo3_dependencies")

rules_pyo3_dependencies()

register_pyo3_toolchains()

load("@rules_pyo3//pyo3:repositories_transitive.bzl", "rules_pyo3_transitive_deps")

rules_pyo3_transitive_deps()

Toolchains

Information about each toolchan can be seen below and in the rule's documentation.

rule	type	mandatory	details
rust_pyo3_toolchain	`@rules_pyo3//pyo3:rust_toolchain_type`	true	Required by the rules to determine what `pyo3` library to link.
pyo3_toolchain	`@rules_pyo3//pyo3:toolchain_type`	false	Used to help build `pyo3`. Users who are building `pyo3` in other ways do not need to set this.

rules_pyo3

Rules

Functions

pyo3_extension

pyo3_toolchain

load("@rules_pyo3//pyo3:defs.bzl", "pyo3_toolchain")

pyo3_toolchain(name)

Define a toolchain which generates config data for the PyO3 for producing extension modules on any target platform.

Note that this toolchain expects the pyo3 crate to be built with the following features:

When using rules_rust's crate_universe, this data can be plubmed into the target using the following snippet.

annotations = {
    "pyo3-build-config": [
        crate.annotation(
            build_script_data = [
                "@rules_pyo3//pyo3:current_pyo3_toolchain",
            ],
            build_script_env = {
                "PYO3_CROSS": "$(PYO3_CROSS)",
                "PYO3_CROSS_LIB_DIR": "$(PYO3_CROSS_LIB_DIR)",
                "PYO3_CROSS_PYTHON_IMPLEMENTATION": "$(PYO3_CROSS_PYTHON_IMPLEMENTATION)",
                "PYO3_CROSS_PYTHON_VERSION": "$(PYO3_CROSS_PYTHON_VERSION)",
                "PYO3_NO_PYTHON": "$(PYO3_NO_PYTHON)",
                "PYO3_PYTHON": "$(PYO3_PYTHON)",
            },
            build_script_toolchains = [
                "@rules_pyo3//pyo3:current_pyo3_toolchain",
            ],
        ),
    ],
    "pyo3-ffi": [
        crate.annotation(
            build_script_data = [
                "@rules_pyo3//pyo3:current_pyo3_toolchain",
            ],
            build_script_env = {
                "PYO3_CROSS": "$(PYO3_CROSS)",
                "PYO3_CROSS_LIB_DIR": "$(PYO3_CROSS_LIB_DIR)",
                "PYO3_CROSS_PYTHON_IMPLEMENTATION": "$(PYO3_CROSS_PYTHON_IMPLEMENTATION)",
                "PYO3_CROSS_PYTHON_VERSION": "$(PYO3_CROSS_PYTHON_VERSION)",
                "PYO3_NO_PYTHON": "$(PYO3_NO_PYTHON)",
                "PYO3_PYTHON": "$(PYO3_PYTHON)",
            },
            build_script_toolchains = [
                "@rules_pyo3//pyo3:current_pyo3_toolchain",
            ],
        ),
    ],
},

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required

rust_pyo3_toolchain

load("@rules_pyo3//pyo3:defs.bzl", "rust_pyo3_toolchain")

rust_pyo3_toolchain(name, pyo3)

Define a toolchain for PyO3 Rust dependencies which power internal rules.

This toolchain is how the rules know which version of pyo3 to link against.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
pyo3	The PyO3 library.	Label	required

pyo3_extension

load("@rules_pyo3//pyo3:defs.bzl", "pyo3_extension")

pyo3_extension(name, srcs, aliases, compile_data, crate_features, crate_root, data, deps, edition,
               imports, proc_macro_deps, rustc_env, rustc_env_files, rustc_flags, version,
               compilation_mode, **kwargs)

Define a PyO3 python extension module.

This target is consumed just as a py_library would be.

PARAMETERS

Name	Description	Default Value
name	The name of the target.	none
srcs	List of Rust `.rs` source files used to build the library. For more details see rust_shared_library.	none
aliases	Remap crates to a new name or moniker for linkage to this target. For more details see rust_shared_library.	`{}`
compile_data	List of files used by this rule at compile time. For more details see rust_shared_library.	`[]`
crate_features	List of features to enable for this crate. For more details see rust_shared_library.	`[]`
crate_root	The file that will be passed to `rustc` to be used for building this crate. For more details see rust_shared_library.	`None`
data	List of files used by this rule at compile time and runtime. For more details see rust_shared_library.	`[]`
deps	List of other libraries to be linked to this library target. For more details see rust_shared_library.	`[]`
edition	The rust edition to use for this crate. Defaults to the edition specified in the rust_toolchain. For more details see rust_shared_library.	`None`
imports	List of import directories to be added to the `PYTHONPATH`. For more details see py_library.imports.	`[]`
proc_macro_deps	List of `rust_proc_macro` targets used to help build this library target. For more details see rust_shared_library.	`[]`
rustc_env	Dictionary of additional `"key": "value"` environment variables to set for rustc. For more details see rust_shared_library.	`{}`
rustc_env_files	Files containing additional environment variables to set for rustc. For more details see rust_shared_library.	`[]`
rustc_flags	List of compiler flags passed to `rustc`. For more details see rust_shared_library.	`[]`
version	A version to inject in the cargo environment variable. For more details see rust_shared_library.	`None`
compilation_mode	The compilation_mode value to build the extension for. If set to `"current"`, the current configuration will be used.	`"opt"`
kwargs	Additional keyword arguments.	none