Expose API to IDEs through .pyi files

[adwait]

(feature proposal)

Some editors (e.g., vscode with pylance) do not load *.so files for Python API hints (microsoft/pylance-release#242 (comment)).

In such cases it would good to have .pyi stub files. This can be autogenerated using tools such as mypy/stubgen (https://mypy.readthedocs.io/en/stable/stubgen.html). However, this will require some work on the cython library packaging.

The pydrake bindings for the drake C++ library did this sucessfully: RobotLocomotion/drake#16987

[adwait]

Suggested previously here: #96

However, this does not work for me out of the box on version 6.0.

[MikePopoloski]

I agree that this is nice to have but it's not something I have time to spend on any time soon. I'd be happy to accept a PR though if you want to tackle it.

[parker-research]

I'd be happy to tackle this!

Both of the following generation methods work:

pip install mypy
stubgen -p pyslang

pip install pybind11-stubgen
pybind11-stubgen pyslang
# Note: Lots of error log messages. Generation still succeeds though.

Curious if anyone has a preference about which one (mypy's stubgen or pybind11-stubgen) is better? Seems like the pybind11 one probably generates richer stubs.

Where in the build process should the stub files be generated? Should they be generated on every pushed commit and version-controlled? Or should they only be generated during the release pipeline? I'm not too sure what the standard is. I think the standard is probably version-controlled.