AcademySoftwareFoundation / AcademySoftwareFoundation/MaterialX

Auto-Generated Stubs for Python Bindings

Open
#2,024 4 comments 0 reactions 0 assignees View on GitHub
help wanted
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.