Repository navigation
[FEA]: Type stubs / .pyi files for cuda.bindings and cuda.core #1963
Description
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.typedmarker)
Additional context
This has been requested by users in internal Slack channels. Type stubs are on the roadmap for the cuda.bindings track.
Activity
mdboom commentedon Apr 22, 2026
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,.pxdand.pyifiles all in sync seems hard to manage.rparolin commentedon Apr 22, 2026
@mdboom We could convert this issue into an EPIC and have subissues for cuda.core and cuda.bindings so its all tracked together.
leofang commentedon Apr 22, 2026
Q:
mdboom commentedon Apr 23, 2026
I take that as a broader level discussion and exploration of options. I take this one to mean -- our best option is to generate
.pyifiles from our generator. (And we still don't have a good solution forcuda-core).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.
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.
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).
1 remaining item
mdboom commentedon May 6, 2026
I've started experimenting with stubgen-pyx, which gets really close to what we need. A few fixes are in order, though:
cimports in generated stubs jon-edward/stubgen-pyx#15# type: ...annotation comments jon-edward/stubgen-pyx#19jon-edward commentedon May 7, 2026
Hello! I’m the creator of stubgen-pyx, I'd be happy to help integrate automatic stub generation or answer any questions
mdboom commentedon May 7, 2026
Thanks, @jon-edward. When we first started exploring this space a few months ago, things looked a lot harder. Thanks for your
stubgen-pyx! I'll reach out and maybe flag you for related reviews as this progresses.mdboom commentedon May 7, 2026
As I work through this, the coolest thing is that once you have
.pyifiles, it's very easy to start doing type checking on those files, which catches not only misspelled type annotations, but uses of undefined members and other things. Since we don't have a Cython linter that does this (yet), it's finding real bugs, such as: #2049This feels magical. 🤯
jon-edward commentedon May 7, 2026
Absolutely, unfortunately Cython tooling is kinda lacking in certain areas which was a major motivator for me to make this
mdboom commentedon May 11, 2026
100% agree. I'm really excited to see both
stubgen-pyxandcython-lintcatch up to pure Python tooling.mdboom commentedon Aug 10, 2026
Moving to cuda.bindings.next milestone. This needs to be after the cybind migration.