AcademySoftwareFoundation / AcademySoftwareFoundation/MaterialX
Auto-Generated Stubs for Python Bindings
- Dominant language
- C++
- Stars
- 2.3k
- Forks
- 451
- Avg merge
- 4d 11h
- Merged PRs (30d)
- 8
Description
Following discussion on Slack, it would be interesting to have auto-generated Stubs for the Python bindings. I would be interest in tackling this issue during devdays this year.
For context, [Stub files](https://typing.readthedocs.io/en/latest/spec/distributing.html#stub-files) can be used to add type hints to packages when it isn't interesting or possible to add them inline. The purpose of type hinting is, among other things, to enable type checking and code completion.
There are tools that generate stubs automatically, such as [MyPy's stubgen](https://mypy.readthedocs.io/en/stable/stubgen.html). If we go down the path of auto-generating the stub files, they could, for example, be created during the GitHub Actions build process, storing the results as an artifact for developers to download, and even be included in the PyPi distributions.
Automatically generated stubs are often, however, not able to cover 100% of the type hints of a package and are instead more of a "template" - the remaining types would need to be "filled in" by hand. From experience, a lot of types already seem to be picked up correctly when running stubgen on MaterialX, but I can't currently estimate what or how much is missing.
I suppose one possibility would also be, instead, to commit the auto-generated stubfiles and fill the remaining bits by hand, but that would involve this extra manual step whenever API changes occur. Otherwise, we could investigate if there are ways to coerce stubgen to pick up more/all types correctly.
Contributor guide
Research direction
No source file or test is named. Start by running MyPy stubgen against the Python bindings and compare which types are generated or missing; then evaluate whether GitHub Actions should generate artifacts or whether stubs should be included in PyPI distributions. Done would require choosing an approach and defining how generated and manually completed types stay current.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- github-actions, python
- Domain
- build-system, developer-experience, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100