Crate pyo3_bindgen

Automatic generation of Rust FFI bindings to Python modules via PyO3. Python modules are analyzed recursively to generate Rust bindings with an identical structure for all public classes, functions, properties, and constants. Any available docstrings and type annotations are also preserved in their Rust equivalents.

Instructions

Option 1: Build script

First, add pyo3_bindgen as a build dependency to your Cargo.toml manifest. To actually use the generated bindings, you will also need to add pyo3 as a regular dependency (or use the re-exported pyo3_bindgen::pyo3 module).

[build-dependencies]
pyo3_bindgen = { version = "0.5" }

[dependencies]
pyo3 = { version = "0.21", features = ["auto-initialize"] }

Then, create a build.rs script in the root of your crate that generates bindings to the selected Python modules. In this example, the bindings are simultaneously generated for the “os”, “posixpath”, and “sys” Python modules. At the end of the generation process, the Rust bindings are written to ${OUT_DIR}/bindings.rs.

With this approach, you can also customize the generation process via pyo3_bindgen::Config that can be passed to Codegen::new constructor, e.g. Codegen::new(Config::builder().include_private(true).build()).

//! build.rs
use pyo3_bindgen::Codegen;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    Codegen::default()
        .module_names(["os", "posixpath", "sys"])?
        .build(format!("{}/bindings.rs", std::env::var("OUT_DIR")?))?;
    Ok(())
}

Afterwards, you can include the generated Rust code via the include! macro anywhere in your crate and use the generated bindings as regular Rust modules. However, the bindings must be used within the pyo3::Python::with_gil closure to ensure that Python GIL is held.

//! src/main.rs
include!(concat!(env!("OUT_DIR"), "/bindings.rs"));

fn main() -> pyo3::PyResult<()> {
    pyo3::Python::with_gil(|py| {
        // Get the path to the Python executable via "sys" Python module
        let python_exe_path = sys::executable(py)?;
        // Get the current working directory via "os" Python module
        let current_dir = os::getcwd(py)?;
        // Get the relative path to the Python executable via "posixpath" Python module
        let relpath_to_python_exe = posixpath::relpath(py, python_exe_path, current_dir)?;

        println!("Relative path to Python executable: '{relpath_to_python_exe}'");
        Ok(())
    })
}

Option 2: Procedural macros (experimental)

As an alternative to build scripts, you can use procedural macros to generate the bindings in-place. First, add pyo3_bindgen_macros as a regular dependency to your Cargo.toml manifest and enable the macros feature.

[dependencies]
pyo3_bindgen = { version = "0.5", features = ["macros"] }

Subsequently, the import_python! macro can be used to generate Rust bindings for the selected Python modules anywhere in your crate. As demonstrated in the example below, Rust bindings are generated for the “math” Python module and can directly be used in the same scope. Similar to the previous approach, the generated bindings must be used within the pyo3::Python::with_gil closure to ensure that Python GIL is held.

As opposed to using build scripts, this approach does not offer the same level of customization via pyo3_bindgen::Config. Furthermore, the procedural macro is quite experimental and might not work in all cases.

use pyo3_bindgen::import_python;
import_python!("math");

// Which Pi do you prefer?
// a) 🐍 Pi from Python "math" module
// b) 🦀 Pi from Rust standard library
// c) 🥧 Pi from your favourite bakery
pyo3::Python::with_gil(|py| {
    let python_pi = math::pi(py).unwrap();
    let rust_pi = std::f64::consts::PI;
    assert_eq!(python_pi, rust_pi);
})

Option 3: CLI tool

For a quick start and testing purposes, you can use the pyo3_bindgen executable to generate and inspect bindings for the selected Python modules. The executable is available as a standalone package and can be installed via cargo.

cargo install --locked pyo3_bindgen_cli

Afterwards, run the pyo3_bindgen executable to generate Rust bindings for the selected Python modules. The generated bindings are printed to STDOUT by default, but they can also be written to a file via the -o option (see pyo3_bindgen --help for more options).

pyo3_bindgen -m os sys numpy -o bindings.rs

Re-exports

pub use pyo3;

Macros

import_python

Procedural macro for generating Rust bindings to Python modules in-place.

Structs

Codegen

Engine for automatic generation of Rust FFI bindings to Python modules.

Config

Configuration for Codegen engine.

Enums

PyBindgenError

Error type for pyo3_bindgen operations.

Type Aliases

PyBindgenResult

Result wrapper for PyBindgenError.