How to make a Python callback funtion match (i.e. become compatible with) a pybind11 C++ class constructor signature?

[TrondMelen]

I try to make a Python interface to an existing API represented by a C++ class where internal events trigger the execution of registered callbacks. I would be grateful if someone can help. Thanks in advance!

The simplified case below demonstrates my problem. The C++ 'My_class' constructor expects one argument of type '(void (data_s const&))', but to Python this is incompatible with '<function my_data_handler at 0x7fef4d1fc180>'. The class instantiation fails with the Python error message "TypeError: __init__(): incompatible constructor arguments." I guess I must either relax the C++ type or tighten the Python type. Right?

The C++ file 'My_class.hpp' defining (header only) 'My_class':

#pragma once

// a struct
struct data_s {
    unsigned int sequence_counter;
    unsigned int byte_count;
    unsigned char array[100];
};

// a function signature taking the struct as argument
typedef void (*data_handler_t)(const struct data_s &);

// class with a constructor and one method/function
class My_class {
public:
    My_class(data_handler_t data_handler) :
        the_data_handler(data_handler) {}

    void run() {
        data_s data;                      // struct allocation
        (the_data_handler)(data);         // the callback is executed here
    }
private:
    data_handler_t the_data_handler{};    // the callback is stored here
};

The pybind11 C++ file 'binder.cpp':

#include <pybind11/pybind11.h>

namespace py = pybind11;

#include "../my_cpp_class/My_class.hpp"

PYBIND11_MODULE(my_py_module, m, py::mod_gil_not_used()) {
    py::class_<My_class>(m, "My_class")
        .def(py::init<data_handler_t>())
        .def("run", &My_class::run);
}

The Python program 'main.py' that fails:

import my_py_module

class data_s:
    def __init__(self):
        self.counter = 0
        self.byte_count = 0
        self.bytearray(100)

def my_data_handler(data: data_s):
    print(f"my_data_handler(): counter is {data.counter}\n")

if __name__ == "__main__":
    api = my_py_module.My_class(my_data_handler)
    api.run()

The failing interactive Python session:

$ python
Python 3.13.5 (main, Jun 25 2025, 18:55:22) [GCC 14.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> exec(open("../my_py_module/main.py").read())
Traceback (most recent call last):
  File "<python-input-0>", line 1, in <module>
    exec(open("../my_py_module/main.py").read())
    ~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "<string>", line 15, in <module>
TypeError: __init__(): incompatible constructor arguments. The following argument types are supported:
    1. my_py_module.My_class(arg0: void (data_s const&))

Invoked with: <function my_data_handler at 0x7fef4d1fc180>
>>> 

Pybind11 is version 2.13.6

[murthy-l]

You are better of using std::function since it is natively supported by pybind11.
Also you will need to expose data_s to python via pybind11 else you will not be able to access elements

with small change i have below working example , i have added inline comments as well. Also,I have just clubbed to one cpp file for simplicity

#include <pybind11/pybind11.h>

namespace py = pybind11;

#include <pybind11/functional.h>
// a struct
struct data_s {
    unsigned int sequence_counter;
    unsigned int byte_count;
    unsigned char array[100];
};

Python
// class with a constructor and one method/function
class My_class {
public:
    My_class(std::function<void *(const struct data_s &)> data_handler) :
        the_data_handler(data_handler) {}

    void run() {
        data_s data;                      // struct allocation
        (the_data_handler)(data);         // the callback is executed here
    }
private:
    // use std::function since it will be natively supported
    std::function<void *(const struct data_s &)> the_data_handler;    // the callback is stored here
};


PYBIND11_MODULE(my_module, m, py::mod_gil_not_used()) {
    // need to expose the data_s struct  in python else python will not know when accessing its elements
    py::class_<data_s>(m, "data_s")
        .def(py::init<>())
        .def_readwrite("sequence_counter", &data_s::sequence_counter)
        .def_readwrite("byte_count", &data_s::byte_count);
    // in case array[100] is needed its not natively supported you will need to use py::array wrapper
    // best would be to use std::vector
    py::class_<My_class>(m, "My_class")
        .def(py::init<std::function<void *(const struct data_s &)>>())
        .def("run", &My_class::run);
}

import my_module as mym

class data_s:
    def __init__(self):
        self.sequence_counter = 0
        self.byte_count = 0
        # To access array[100] you will need to to use py::array and write a procedure for it

def my_data_handler(data: data_s):
    # below print will print garbage value for data.sequence_counter since its not initialized in cpp
    print(f"my_data_handler(): counter is {data.sequence_counter}\n")

api=mym.My_class(my_data_handler)
api.run()

[TrondMelen]

Thank you very much Murthy L, for taking the time to look into the problem, and for suggesting a solution. This looks very promising! Best regards, Trond ***@***.***?anonymous&ismsaljsauthenabled&ep=owaSlotsEmailSignature> Book time to meet with ***@***.***?anonymous&ismsaljsauthenabled&ep=owaSlotsEmailSignature>

…

________________________________ Fra: Murthy L ***@***.***> Sendt: tirsdag 10. mars 2026 10:58 Til: pybind/pybind11 ***@***.***> Kopi: Trond Melen ***@***.***>; Author ***@***.***> Emne: Re: [pybind/pybind11] How to make a Python callback funtion match (i.e. become compatible with) a pybind11 C++ class constructor signature? (Discussion #5996) You are better of using std::function since it is natively supported by pybind11. Also you will need to expose data_s to python via pybind11 else you will not be able to access elements with small change i have below working example , i have added inline comments as well. Also,I have just clubbed to one cpp file for simplicity #include <pybind11/pybind11.h> namespace py = pybind11; #include <pybind11/functional.h> // a struct struct data_s { unsigned int sequence_counter; unsigned int byte_count; unsigned char array[100]; }; Python // class with a constructor and one method/function class My_class { public: My_class(std::function<void *(const struct data_s &)> data_handler) : the_data_handler(data_handler) {} void run() { data_s data; // struct allocation (the_data_handler)(data); // the callback is executed here } private: // use std::function since it will be natively supported std::function<void *(const struct data_s &)> the_data_handler; // the callback is stored here }; PYBIND11_MODULE(my_module, m, py::mod_gil_not_used()) { // need to expose the data_s struct in python else python will not know when accessing its elements py::class_<data_s>(m, "data_s") .def(py::init<>()) .def_readwrite("sequence_counter", &data_s::sequence_counter) .def_readwrite("byte_count", &data_s::byte_count); // in case array[100] is needed its not natively supported you will need to use py::array wrapper // best would be to use std::vector py::class_<My_class>(m, "My_class") .def(py::init<std::function<void *(const struct data_s &)>>()) .def("run", &My_class::run); } import my_module as mym class data_s: def __init__(self): self.sequence_counter = 0 self.byte_count = 0 # To access array[100] you will need to to use py::array and write a procedure for it def my_data_handler(data: data_s): # below print will print garbage value for data.sequence_counter since its not initialized in cpp print(f"my_data_handler(): counter is {data.sequence_counter}\n") api=mym.My_class(my_data_handler) api.run() — Reply to this email directly, view it on GitHub<#5996 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/B3XEY722UYLZPBXTCKHXJ534P7ROHAVCNFSM6AAAAACWAPN3OWVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTMMBWGYZDKNY>. You are receiving this because you authored the thread.Message ID: ***@***.***>

[gistrec]

Adding to @murthy-l - one small but important correction: the std::function return type should be void, not void *

The original callback type is:

using data_handler_t = void (*)(const data_s&);

so the pybind11-friendly version should be:

std::function<void(const data_s&)>

not:

std::function<void*(const data_s&)>

If the Python callback returns None, void * would require pybind11 to convert that return value into a raw pointer, which is not what the original C++ callback signature means

A corrected binding would look like this:

#include <pybind11/pybind11.h>
#include <pybind11/functional.h>

namespace py = pybind11;

#include "My_class.hpp"

PYBIND11_MODULE(my_py_module, m) {
    py::class_<data_s>(m, "data_s")
        .def(py::init<>())
        .def_readwrite("sequence_counter", &data_s::sequence_counter)
        .def_readwrite("byte_count", &data_s::byte_count);

    py::class_<My_class>(m, "My_class")
        .def(py::init<std::function<void(const data_s&)>>())
        .def("run", &My_class::run);
}

And the C++ class should store the same type if the callback is used later:

#include <functional>
#include <utility>

class My_class {
public:
    My_class(std::function<void(const data_s&)> data_handler)
        : the_data_handler(std::move(data_handler)) {}

    void run() {
        data_s data{};
        the_data_handler(data);
    }

private:
    std::function<void(const data_s&)> the_data_handler;
};

The important part is #include <pybind11/functional.h> - that is what enables conversion between a Python callable and std::function<void(const data_s&)>

[TrondMelen]

After I few months, I returned to this task of making a Python interface to an existing API represented by a C++ class where internal events trigger the execution of registered callbacks. Now it seems to work perfectly.

Thank you very much both Murthy L and Aleksandr Kovalko, for taking the time to investigate and respond! Your advice was very welcome.

[TrondMelen]

Mark ass answered