A recommended way to generate type annotations for boost::python code?


is there a good method to generate type annotations for C++ code bound to Python using boost::python?

A Google search didn’t yield much information. While I recognize this task may involve a significant amount of manual work, I’m still hoping someone must have already tackled this a can share some valuable insights or techniques.

Any recommendations are appreciated,


To be clear, you want the wrappers generated by boost::python to have type annotations added?

Karl: Yes.

This is a task I’m undertaking for the company I work for. We’ve explored several solutions, such as embedding the required information in comments within Boost files and utilizing a tool to generate .pyi files, or creating the annotations manually.

Given that boost::python is typically the preferred solution for creating C++/Python bindings, I was hoping that someone may have already devised a method to automate this task, or at least streamline parts of it.


We wanted a similar thing at my company. Our solution is far from perfect, but still much better than nothing. That might help you start, and if you find how to perfect it: let me know, I’ll be really happy.

our process leverages stubgen . This a tool provided by mypy that imports the C++ bindings once and infers typing infos from it

  • The cmake target building any C++ bindings has an additional task to run stubgen
  • stubgen creates a pyi file, that we’ll copy alongside the binary .so of our bindings

What works:

  • stubgen is able to properly detect all classes and free functions. It means our IDE setup can warn people if they do typos on class/method/function names

What does not:

  • function arguments and return values are not typed
  • I get a weird first argument named boost on many functions, that confuses IDEs

I heard about pybind11-stubgen that looks more flexible (notably I believe that it can read docstrings?), that could bring you even further in your path