nanobind-stubgen - Generate python stub files for code completion

[cansik]

Since python development with nanogui was difficult due to missing type information, I have written a simple (and basic) tool to create .pyi files for nanobind modules: nanobind-stubgen.

The tool uses the __doc__ string of nb_* objects to infer the correct types and works with already compiled modules. For example to generate nanogui bindings, use the following lines of code:

# install dependencies
pip install nanogui nanobind-stubgen

# generate nanogui stubs
nanobind-stubgen nanogui

The generate files can now be found in the ./nanogui directory.

⚠️ Currently, the generated stub files are not error-free and cannot be used directly for mypy type checking without manual clean-up.

Related to: #60 & mitsuba-renderer/nanogui#79

[torokati44]

Have you tried mypy's subgen?
https://mypy.readthedocs.io/en/stable/stubgen.html
It sounds like this does basically the same thing.
If so, what's the reason for it not being appropriate for you?

[cansik]

Yes, I tried mypy's stubgen and it returns an __init__.pyi with the following content for the module nanogui:

def cmake_dir(): ...

Also with pybind11-stubgen I was not successful.

Have you been able to generate stubs with either of the tools?

[torokati44]

Yes, mypy's stubgen worked fine for me, but now that I compared it to your stuff, it's way less useful:

For the same member function, mypy's stubgen generates this: (self, *args, **kwargs) -> Any:
And nanobind-stubgen this: (self, arg: int, /) -> float:

So, thanks! :D

[torokati44]

Although this is missing members (simple fields), and enum constants.

[cansik]

Ok, that's interesting, maybe there is something wrong with the mypy tools on my system.
And yes, I am still working on constructors, enums, constants and properties.

[torokati44]

I simply ran this BTW: stubgen -m test_ext next to the test_ext.so file.

[torokati44]

A few suggestions for the generated stubs:

• Qualifying types with module paths that are in the same module is unnecessary.
• Repeating the stub signature in the docstring is not really useful.
• At least from typing import Optional (and any other types from typing used by the stub generator itself) could be added.

Also, if you found a way to include the proper imports, that would be great...

[cansik]

Thanks for the suggestions, I have implemented support for constructors, enums, overloaded functions and constants. And I tried to fix some of the issues regarding imports. The function signature is taken directly from the doc string, so I do not really have much control regarding the import path for argument types.

Version 0.1.1 is ready.

[wjakob]

Dear @cansik,

thank you for building this, it looks great! I had actually planned to work on an stub generator for nanobind as well, but you beat me to it. This actually leads me to a somewhat awkward question:

Would you be willing to co-maintain this software (and share admin privileges on GitHub+PyPI)? Alternatively (if you prefer to be in charge), would you mind giving your project a different name? The reason for this request is that I had planned to call my tool nanobind-stubgen as well -- it's just the obvious name for a stub generator, and the name at least suggests that it is the official nanobind solution for this problem.

Features on my TODO list would be the ability to customize the stub generation. Some of my projects need specialized transformations on top of the initial output, so it should be possible to import the stub generator from Python and add callback hooks that modify class/function signatures.

Thanks,
Wenzel

[cansik]

Hi @wjakob, thanks for your message and don't worry, I'm happy to share the GitHub & PyPi repo with you to release an official solution. You should already be invited to Github and PyPI.

My approach is only based on Python's inspection functionality, but for an official solution it would make more sense to extend mypy to support nanobind as mentioned in #171.

What kind of approach do you have in mind?

[wjakob]

Awesome, many thanks for this! It will still take me some time before I can be active on this front (I am swamped with university TODO items at the moment). In any case, it is already a relief to know that we will be able to work together on making this an official solution for the inevitable nanobind+stub generation issue.

Regarding your question: I am not sure. Building on MyPy naturally has advantages, but I wonder how receptive the MyPy team would be towards a PR that tweaks low-level details pertaining to a single binding framework. It might be worth a try and submit @yosh-matsuda's changes as an official PR to gauge their reaction.

That aside, I feel am sure that there are always cases where people will want more fine-grained control over what ends up in the stub files/sphinx. I don't know enough about the MyPy stub generator yet to see if it can handle that level of customization.

[qnzhou]

Thanks for this work! I am wondering what is the recommended way of integrating stub generation with the build process (e.g. with scikit-build as in nanobind_example). Specifically, I would love to auto-generated stub files and add it to the package when I pip install or pip wheel the package. However, it seems the nanobind-stubgen module requires the module to be already installed.

[tmsrise]

Piggy backing on this to propose that stub generation should be an included option that is integrated directly into nanobind (or pybind11). I want CMake to build my library and build bindings that are actually parseable by vscode/pylance or other security minded tools, instead of jumping through a thousand hoops to get basic linting and autocompletion working.

Right now I have to have the user pip install the generator, then have CMake run a python script that tricks pybind11-stubgen into thinking its current python environment is in the build directory before running it. I also have to hardcode my enum class locations into the command, for whatever reason.

[rzhikharevich-wmt]

I think the approach used by nanobind-stubgen is flawed because the doc string signatures aren't always valid Python code (e.g. when default values have a __str__ that does not return a valid Python expression), and in general extracting signatures from doc strings is prone to all sorts of fragility.

I see a few approaches that would be more reliable:

• Have nanobind define __signature__: inspect.Signature for all functions. This has the benefit of using a standard attribute and potentially allowing to use something like mypy-stubgen with minimal changes. One problem is that this signature would have to be a union of all overloads which would lose information about individual overloads.
• Export a nanobind-specific Python API that would return a list of overloaded signatures for a given function.
• Call the @typing.overload decorator during module initialization and pass it a special nb_overload wrapper object, then use typing.get_overloads.

[cansik]

Yes, I agree that this should not be a "post-processing" tool. For me it was a workaround to use nanogui as a python library, otherwise it was just very difficult to develop almost blind.

It was never intended to be a complete solution to the problem, and maybe someone with more knowledge, experience and passion for nanobind could take over the development of such a tool?

[wjakob]

I created a tracking issue #420 to discuss a potential builtin mechanism for stub generation in a future version of nanobind.