| 1 |
# Bindings |
| 2 |
|
| 3 |
Maturin supports several kinds of bindings, some of which are automatically |
| 4 |
detected. You can also pass `-b` / `--bindings` command line option to manually |
| 5 |
specify which bindings to use. |
| 6 |
|
| 7 |
## `pyo3` |
| 8 |
|
| 9 |
[pyo3](https://github.com/PyO3/pyo3) is Rust bindings for Python, |
| 10 |
including tools for creating native Python extension modules. |
| 11 |
It supports CPython, PyPy, and GraalPy. |
| 12 |
|
| 13 |
maturin automatically detects pyo3 bindings when it's added as a dependency in `Cargo.toml`. |
| 14 |
|
| 15 |
### `Py_LIMITED_API`/abi3 |
| 16 |
|
| 17 |
pyo3 bindings has `Py_LIMITED_API`/abi3 support, enable the `abi3` feature of the `pyo3` crate to use it: |
| 18 |
|
| 19 |
```toml |
| 20 |
pyo3 = { version = "0.25", features = ["abi3"] } |
| 21 |
``` |
| 22 |
|
| 23 |
You may additionally specify a minimum Python version by using the `abi3-pyXX` |
| 24 |
format for the pyo3 features, where `XX` is corresponds to a Python version. |
| 25 |
For example `abi3-py37` will indicate a minimum Python version of 3.7. |
| 26 |
|
| 27 |
> **Note**: Read more about abi3 support in [pyo3's |
| 28 |
> documentation](https://pyo3.rs/latest/building-and-distribution#py_limited_apiabi3). |
| 29 |
|
| 30 |
### Cross Compiling |
| 31 |
|
| 32 |
pyo3 bindings has decent cross compilation support. |
| 33 |
For manylinux support the [manylinux-cross](https://github.com/rust-cross/manylinux-cross) docker images can be used. |
| 34 |
|
| 35 |
> **Note**: Read more about cross compiling in [pyo3's |
| 36 |
> documentation](https://pyo3.rs/latest/building-and-distribution#cross-compiling). |
| 37 |
|
| 38 |
## `cffi` |
| 39 |
|
| 40 |
Cffi wheels are compatible with all python versions including pypy. If `cffi` |
| 41 |
isn't installed and python is running inside a virtualenv, maturin will install |
| 42 |
it, otherwise you have to install it yourself (`pip install cffi`). |
| 43 |
|
| 44 |
Maturin uses cbindgen to generate a header file for [supported Rust |
| 45 |
types](https://github.com/eqrion/cbindgen/blob/master/docs.md#supported-types). |
| 46 |
The header file can be customized by configuring cbindgen through a |
| 47 |
`cbindgen.toml` file inside your project root. Aternatively you can use a build |
| 48 |
script that writes a header file to `$PROJECT_ROOT/target/header.h`, like so: |
| 49 |
|
| 50 |
```rust |
| 51 |
use cbindgen; |
| 52 |
use std::env; |
| 53 |
use std::path::Path; |
| 54 |
|
| 55 |
fn main() { |
| 56 |
let crate_dir = env::var("CARGO_MANIFEST_DIR").unwrap(); |
| 57 |
|
| 58 |
let bindings = cbindgen::Builder::new() |
| 59 |
.with_no_includes() |
| 60 |
.with_language(cbindgen::Language::C) |
| 61 |
.with_crate(crate_dir) |
| 62 |
.generate() |
| 63 |
.unwrap(); |
| 64 |
bindings.write_to_file(Path::new("target").join("header.h")); |
| 65 |
} |
| 66 |
``` |
| 67 |
|
| 68 |
Maturin uses the cbindgen-generated header to create a module that exposes `ffi` and |
| 69 |
`lib` objects as attributes. See the [cffi docs](https://cffi.readthedocs.io/en/latest/using.html) |
| 70 |
for more information on using these `ffi`/`lib` objects to call the Rust code |
| 71 |
from Python. |
| 72 |
|
| 73 |
> **Note**: Maturin _does not_ automatically detect `cffi` bindings. You _must_ |
| 74 |
> specify them via either command line with `-b cffi` or in `pyproject.toml`. |
| 75 |
|
| 76 |
Maturin automatically detect `cffi` bindings, but only if there is no pyo3 |
| 77 |
dependency. You can specify `cffi` explicitly via either command line with |
| 78 |
`-b cffi` or in `pyproject.toml`. |
| 79 |
|
| 80 |
## `bin` |
| 81 |
|
| 82 |
Maturin also supports distributing binary applications written in Rust as |
| 83 |
Python packages using the `bin` bindings. Binaries are packaged into the wheel |
| 84 |
as "scripts" and are available on the user's `PATH` (e.g. in the `bin` |
| 85 |
directory of a virtual environment) once installed. |
| 86 |
|
| 87 |
Maturin automatically detect `bin` bindings, but only if there |
| 88 |
is only a binary target and no pyo3 dependency or cdylib target. You can |
| 89 |
specify `bin` explicitly via either command line with `-b bin` or in `pyproject.toml`. |
| 90 |
|
| 91 |
### Both binary and library? |
| 92 |
|
| 93 |
Shipping both a binary and library would double the size of your wheel. Consider instead exposing a CLI function in the library and using a Python entrypoint: |
| 94 |
|
| 95 |
```rust |
| 96 |
#[pyfunction] |
| 97 |
fn print_cli_args(py: Python) -> PyResult<()> { |
| 98 |
// This one includes python and the name of the wrapper script itself, e.g. |
| 99 |
// `["/home/ferris/.venv/bin/python", "/home/ferris/.venv/bin/print_cli_args", "a", "b", "c"]` |
| 100 |
println!("{:?}", env::args().collect::<Vec<_>>()); |
| 101 |
// This one includes only the name of the wrapper script itself, e.g. |
| 102 |
// `["/home/ferris/.venv/bin/print_cli_args", "a", "b", "c"])` |
| 103 |
println!( |
| 104 |
"{:?}", |
| 105 |
py.import("sys")? |
| 106 |
.getattr("argv")? |
| 107 |
.extract::<Vec<String>>()? |
| 108 |
); |
| 109 |
Ok(()) |
| 110 |
} |
| 111 |
|
| 112 |
#[pymodule] |
| 113 |
fn my_module(m: &Bound<'_, PyModule>) -> PyResult<()> { |
| 114 |
m.add_wrapped(wrap_pyfunction!(print_cli_args))?; |
| 115 |
|
| 116 |
Ok(()) |
| 117 |
} |
| 118 |
``` |
| 119 |
|
| 120 |
In pyproject.toml: |
| 121 |
|
| 122 |
```toml |
| 123 |
[project.scripts] |
| 124 |
print_cli_args = "my_module:print_cli_args" |
| 125 |
``` |
| 126 |
|
| 127 |
## `uniffi` |
| 128 |
|
| 129 |
uniffi bindings use [uniffi-rs](https://mozilla.github.io/uniffi-rs/) to generate Python `ctypes` bindings |
| 130 |
from an interface definition file. uniffi wheels are compatible with all python versions including pypy. |