Preparing Your Project's API

For optimal performance with Pybind11 Weaver, your project's API needs to be adequately prepared.

Self-Contained API

Firstly, it would be beneficial if your API was self-contained, implying that it shouldn't rely on libraries outside the standard library.

If your API relies on other libraries and you haven't set these dependencies as inputs to Pybind11 Weaver, the classes/enums within these dependencies won't be generated, potentially disrupting your API on the Python side.

Setting these dependencies as inputs to Pybind11 Weaver could lead to an endless loop, as your dependencies may have further dependencies.

Fortunately, there are numerous ways to obscure dependencies, with the pimpl idiom and opaque pointers being excellent choices.

C With OO API

Pybind11 functions optimally with a C API using an OO style, necessitating certain checks before using Pybind11 Weaver.

Ideally, your API should only contain:

1. Namespace
2. Function
3. Class
4. Enum

If your API adheres to this rule, Pybind11 Weaver will function smoothly. If no customization is necessary, you can directly utilize the generated code.

For example, since C can only have functions, struct, and enum, a C style API will certainly work seamlessly.

If your API utilizes anything related to templates, you may have to write some custom binding code. In summary:

1. Template functions and Template classes should function in most cases, provided you can specify all possible template instances (specialization and instantiation). Technically, these instances are merely plain classes/functions the compiler generates for you, there's not much difference between them and regular classes/functions, but note that Pybind11 Weaver will generate the binding for these template instances with a mangled name.
2. Metaprogramming is not supported, and any API utilizing metaprogramming may break the generator itself. Therefore, it's advisable to avoid using metaprogramming in your API.