[FEA]: Type stubs / .pyi files for cuda.bindings

[rparolin]

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

The cuda.bindings module is implemented as a C extension, which means type checkers (mypy, pyright) and IDEs (VS Code, PyCharm) cannot introspect the API for autocompletion, inline documentation, or static type checking without explicit type information.

Describe the solution you'd like

Ship PEP 561-compliant type stubs (.pyi files) for cuda.bindings and other public modules. Ideally these would be:

• Auto-generated alongside the bindings (to stay in sync with the C API)
• Distributed inline with the package (with a py.typed marker)

Additional context

This has been requested by users in internal Slack channels. Type stubs are on the roadmap for the cuda.bindings track.

[mdboom]

The recent work on the generator will make this a whole lot easier. Because cuda-bindings is largely generated, this should be doable.

It would also be nice to do this for cuda-core, but Cython doesn't make that easy for hand-written code. We would probably need to create some tool to automatically extract this, since keeping .pyx, .pxd and .pyi files all in sync seems hard to manage.

[rparolin]

@mdboom We could convert this issue into an EPIC and have subissues for cuda.core and cuda.bindings so its all tracked together.

[leofang]

Q:

• What is the relation between this issue and [FEA]: Add .pyi files so IDEs can provide autocompletion #928?
• Why isn't the current type annotation enough? Which module was being flagged? We actually already generated enough type annotations for driver/runtime/nvrtc (via cython-gen).

[mdboom]

What is the relation between this issue and #928?

I take that as a broader level discussion and exploration of options. I take this one to mean -- our best option is to generate .pyi files from our generator. (And we still don't have a good solution for cuda-core).

Why isn't the current type annotation enough?

Type annotations in Cython code (or any compiled extension) can not be read by language servers, like pyright, pylance, ty, mypy etc. which are all designed to parse, but not import, code. .pxd files /feel/ like they should work, but they a mix of C and Cython-specific types which are not the same thing as the types that make up the Python-side typing system.

Which module was being flagged?

Not sure what you mean. I just fired up VSCode and Emacs when I got here and was disappointed that it didn't work well with cuda_bindings.

We actually already generated enough type annotations for driver/runtime/nvrtc (via cython-gen).

Cython generates some signature metadata etc., but this can't be used by a language server and also is wrong in a bunch of ways (see #928).