add *.pyi stub generation support for bindings in rosetta.so #588
+20
−2
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Adds the
--stubsflag to build.py for building pyrosetta, which uses pybind11-stubgen to inspect the C++ bindings generated by binder/pybind11 and generates*.pyitype annotation stub files in the rosetta directory. This allows static type checkers to see the members, arguments, and (most of the time*) parameter types included in pyrosetta. Adding**/*.pyifiles to thesetup.pypackage_data list means these stubs will be included automatically with any distribution, meaning it should be plug-and-play with a new release.This PR adds a dependence on an external pypa package for stub generation (it's imported in the generate_stubs method so won't affect the process if unspecified) and I'm not familiar enough with the setuptools / ez_setup build pipeline to know how that should be integrated as a requirement. Thoughts? Should it be included as a submodule like other dependencies? Currently I just throw an error in generate_stubs in
build.pyif--stubsis specified but the package isn't included.I think this will make the experience a lot easier for new users. I've tested it (installing from the
.whlfile in a fresh environment) in VSCode, and it should be compatible with static type analyzers and google colab as well!*pybind11-stubgen uses the docstrings automatically generated by pybind11 to infer by-reference parameter types. If a module member is bound by pybind11 which references a type which has itself not yet been bound, the docstring can't use the python type name (since where the type should sit in the python module tree hasn't been specified) so it defaults to the C++ type instead (see the pybind11 documentation). Pybind11-stubgen will still include these C++ docstrings in the
*.pyifiles, which removes ambiguity for users most of the time [the user sometimes needs to connect the dots thatstd::shared_ptr<class core::pose::PDBInfo>corresponds topyrosetta.rosetta.core.pose.PDBInfo] even if it can't properly annotate parameter types accordingly. This could theoretically be fixed by updating binder to run in two passes, binding all classes first and then all functions, but that would require a massive refactor for only marginal gain.