24 releases

0.14.24 Mar 16, 2024
0.14.21 Jan 30, 2024
0.14.19 Sep 14, 2023
0.14.18 May 21, 2023
0.13.11 Nov 30, 2021

#139 in FFI

Download history 163/week @ 2024-01-27 265/week @ 2024-02-03 157/week @ 2024-02-10 226/week @ 2024-02-17 191/week @ 2024-02-24 271/week @ 2024-03-02 407/week @ 2024-03-09 555/week @ 2024-03-16 216/week @ 2024-03-23 170/week @ 2024-03-30 303/week @ 2024-04-06 583/week @ 2024-04-13 530/week @ 2024-04-20 597/week @ 2024-04-27 403/week @ 2024-05-04 368/week @ 2024-05-11

2,097 downloads per month
Used in edge-transformers

MIT license

3.5K SLoC

Generates CPython bindings for Interoptopus.


Assuming you have written a crate containing your FFI logic called example_library_ffi and want to generate CPython bindings for Python 3.7+, follow the instructions below.

Inside Your Library

Add Interoptopus attributes to the library you have written, and define an inventory function listing all symbols you wish to export. An overview of all supported constructs can be found in the reference project.

use interoptopus::{ffi_function, ffi_type, Inventory, InventoryBuilder, function};

pub struct Vec2 {
    pub x: f32,
    pub y: f32,

pub extern "C" fn my_function(input: Vec2) -> Vec2 {

pub fn my_inventory() -> Inventory {

Add these to your Cargo.toml so the attributes and the binding generator can be found (replace ... with the latest version):

crate-type = ["cdylib", "rlib"]

interoptopus = "..."
interoptopus_backend_cpython = "..."

Create a unit test in tests/bindings.rs which will generate your bindings when run with cargo test. In real projects you might want to add this code to another crate instead:

use interoptopus::util::NamespaceMappings;
use interoptopus::{Error, Interop};

fn bindings_cpython_cffi() -> Result<(), Error> {
    use interoptopus_backend_cpython::{Config, Generator};

    let library = example_library_ffi::my_inventory();

    Generator::new(Config::default(), library)


Now run cargo test.

If anything is unclear you can find a working sample on Github.

Generated Output

The output below is what this backend might generate. Have a look at the Config struct if you want to customize something. If you really don't like how something is generated it is easy to create your own.

from __future__ import annotations
import ctypes
import typing

T = typing.TypeVar("T")
c_lib = None

def init_lib(path):
    """Initializes the native library. Must be called at least once before anything else."""
    global c_lib
    c_lib = ctypes.cdll.LoadLibrary(path)
    c_lib.my_function.argtypes = [Vec2]
    c_lib.my_function.restype = Vec2

def my_function(input: Vec2) -> Vec2:
    return c_lib.my_function(input)

TRUE = ctypes.c_uint8(1)
FALSE = ctypes.c_uint8(0)

class Vec2(ctypes.Structure):
    # These fields represent the underlying C data layout
    _fields_ = [
        ("x", ctypes.c_float),
        ("y", ctypes.c_float),

    def __init__(self, x: float = None, y: float = None):
        if x is not None:
            self.x = x
        if y is not None:
            self.y = y

    def x(self) -> float:
        return ctypes.Structure.__get__(self, "x")

    def x(self, value: float):
        return ctypes.Structure.__set__(self, "x", value)

    def y(self) -> float:
        return ctypes.Structure.__get__(self, "y")

    def y(self, value: float):
        return ctypes.Structure.__set__(self, "y", value)