[FEA]: Introduce `.pyi` files for signatures and docstrings

[Andy-Jost]

Area

cuda.core

Is your feature request related to a problem? Please describe.

See comment https://github.com/NVIDIA/cuda-python/pull/1316/changes#r2598892097

Describe the solution you'd like

Explore using .pyi files for type signatures and docstrings. Use .pyx only for implementation. If a good solution is found, update docs/developer-guide.md.

[Andy-Jost]

It appears that .pyi files would introduce a significant maintenance burden. Both docstrings and type annotations would need to be repeated in .pyx and .pyi files. It seems to me that if we want to use .pyi files, we need a way to auto-generate them. Any comment @mdboom?

Benefits

1. IDE Support: Modern IDEs (VS Code, PyCharm) don't import Cython modules for autocomplete. Without .pyi stubs, users get no autocomplete, type hints, or go-to-definition for .pyx modules. Stubs enable full IDE functionality.
2. Static Type Checking: Tools like mypy can validate user code against the library's type signatures, catching errors before runtime.
3. Documentation Generation: Sphinx and other doc tools can more reliably extract signatures from .pyi files than from compiled Cython modules.

Costs

1. Significant Duplication: Both type annotations and docstrings must remain in .pyx files for runtime functionality (help(), doc, Cython type enforcement). Adding .pyi files means maintaining this information in two places.
2. Maintenance Burden: Stubs must be kept in sync with implementation. Any signature or docstring change requires updating both files, creating high risk of drift.
3. No Runtime Effect: .pyi files are purely for static analysis. They don't replace anything in .pyx files; they only duplicate it for tooling visibility.
4. Tooling Gaps: Auto-generation tools like stubgen produce incomplete stubs for Cython code, requiring manual refinement and ongoing maintenance.

[leofang]

Please make sure @mdboom is looped in. We could also consider closing this as a duplicate in favor of #928.

[mdboom]

I agree that hand-written .pyi files would be a huge burden.

I see a couple ways forward:

• Use a tool that can import an already built Python extension and generate stubs from it, such as stubgen in "inspect mode". That tools doesn't do a perfect job because our docstrings (particularly the generated ones) use a mixture of C and Python types. I go into more detail about that in the other bug
• Convert our Cython files to use the new "Pure python" syntax, and then use a stubgen in "no import mode". This is a simple process -- it basically just strips the implementation from all functions and outputs the result.

In either path, you integrate stubgen as part of the build process, and you wouldn't check the .pyi files into source control.

Both of these paths are significant work, though I feel like the second one is ultimately more sustainable from a "leveraging where the Python community is going" perspective. We could do it incrementally -- convert a single .pyx file to the new syntax, and learn how difficult that is, whether LLMs or other tooling are helpful, etc.

[Andy-Jost]

Duplicate of #928