[FEA]: Add .pyi files so IDEs can provide autocompletion

[mdboom]

Is this a duplicate?

• I confirmed there appear to be no duplicate issues for this request and that I agree to the Code of Conduct

Area

General cuda-python

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

Python language servers and type checkers (e.g. pylance, ruff-lsp, pyre, mypy) generally don't import code, so extension modules, such as those from Cython, are opaque to them.

Describe the solution you'd like

If we provided .pyi files alongside our extension modules, these tools would do a better job at type-checking and providing autocompletions etc.

While I have no direct experience with it, cythonbuilder claims to automatically generate them. Other options may include mypy's stubgen or pyright's --create-stub feature.

If that doesn't work, we may be able to generate .pyi alongside most of the generated code by modifying our generator.

We will also need some way (through CI or the pre-commit hook, if possible) to ensure that the .pyi files are staying in-sync with the .pyx files.

We probably don't need to check in the .pyi files into the repo if we can generate them at build time (alongside the .cpp files).

Describe alternatives you've considered

No response

Additional context

No response

[mdboom]

cythonbuilder

Seems to not support some more recent Cython syntax that we are using. I think any tool that attempts to parse Cython that /isn't/ Cython is likely to run into this maintenance burden. Similar tools Cystub and CythonPEG are in a similar state. None of these tools likes our Cython code out-of-the-box today.

There is a 2019 Cython issue to generate .pyi files from Cython.

pyright

Pyright's --createstubs command parses Python code, so isn't useful for Cython.

mypy

mypy's stubgen command gets the closest. It doesn't parse the .pyx file, but instead imports and inspects the .so module. It does a good job of extracting what's in there, but it doesn't get all the way. For example, here is a class:

class CUDA_BATCH_MEM_OP_NODE_PARAMS_v2_st:
    count: Incomplete
    ctx: Incomplete
    flags: Incomplete
    paramArray: Incomplete
    def __init__(self, *args, **kwargs) -> None: ...
    def getPtr(self) -> Any: ...
    def __reduce__(self): ...

class CUDA_CHILD_GRAPH_NODE_PARAMS(CUDA_CHILD_GRAPH_NODE_PARAMS_st):
    @classmethod
    def __init__(cls, *args, **kwargs) -> None: ...

So, it's getting the inheritance right, but the types of the members are marked as Incomplete. (I'm not sure those are introspectable).

Functions, likewise, lack a signature. This is surprising, since an introspectable signature is present -- mypy isn't picking it up, though, maybe because the cython function doesn't look enough like a regular Python function.

cuArray3DCreate: _cython_3_0_12.cython_function_or_method

While this isn't super useful for type-checking, this alone would be a useful improvement to autocompletion. For example, in VSCode:

Before:

After:

My own take is:

• mypy is the leading option for this. mypy is indisputably a "popular and maintained" package.
• It might be worth a short investigation to see if some combination of Cython build flags and changes to mypy can improve the amount of information in the .pyi file.
• It's an open question as to whether it's worth including these "partially specified" .pyi files.

EDIT: Relevant mypy issue