Repository navigation
Description
Projects such as CuPy, cuda-core and RAPIDS cimport the cy* modules of cuda.bindings. Each builds against its own cuda-bindings release, and in a user's environment they all share one installed cuda-bindings. That works when each project declares a floor (cuda-bindings>=<floor>,<next major>; see #3459): the environment resolves to a release at or above the highest floor, and modules built against older releases keep working, because at import Cython checks only the functions a module uses (tested with Cython 3.2.9):
- a used function that is missing raises
ImportError: ... does not export expected C function ...; - a used function whose argument or return types changed raises
TypeError: ... has wrong signature; - parameter renames, removed functions that the module does not use, and
except-clause changes pass. Theexceptclause is not checked at all.
#1030 states this as the intended contract ("Projects built against cuda-bindings 12.x (via cimport) should work with all 12.y, for arbitrary x <= y"), after Cython ABI breaks in 11.x (conda-forge/cuda-python-feedstock#15) and 12.x (#274). Item 5 of the support policy (12.x, 13.x, last updated in #2977) does not promise it: "due to Cython limitations a new minor release of this module could require Cython layer users to rebuild their projects and update their pinning to this module." A downstream project that takes this at its word caps cuda-bindings at the minor it built against, and two projects built against different minors can then not be installed together.
In practice the layer is already append-only. Comparing the __pyx_capi__ capsule signatures of the cy* modules (the function check of toolshed/check_cython_abi.py, #1929) between consecutive releases from 12.9.3 to 12.9.10 and from 13.0.2 to 13.5.0, functions were only added, with two exceptions: cynvrtc dropped nvrtcGetNVVM and nvrtcGetNVVMSize in 12.9.8, and the cy_nvml preview module became cynvml in 13.2.0 when NVML was made public (#1544).
Proposal
- Reword item 5 in both
support.rstfiles as the guarantee from CI: Add integration tests to covercuda.bindingsABI stability #1030: within a CUDA major,cy*functions are only added. An existing function keeps its argument types, return type andexceptclause, and is not removed; such changes wait for the next major. - Run
toolshed/check_cython_abi.pyin CI on thecy*modules against the latest release of the same major, downloading that release's wheel as the baseline instead of committing ABI files (the alternative suggested in Detect __pyx_capi__ changes in testing #1067), and fail on missing or changed symbols. This is the integration job that CI: Add integration tests to covercuda.bindingsABI stability #1030 tracks. Two gaps to close:- With
cuda-bindings13.5.0 and Cython 3.2.9, the tool's.pxdstruct parser fails oncydriver.pxd,cycudla.pxdandcycufile.pxd(the parse error surfaces asAttributeError: '_thread._local' object has no attribute 'cython_errors_stack'), sogeneratestops at the first of them. - Capsule signatures do not include the
exceptclause, and Cython does not check it at import, soexceptchanges need a separate comparison of the.pxddeclarations.
- With
-- Leo's bot
Activity
mdboom commentedon Nov 17, 2026
Agree with all of this in principle as a reasonable goal. Details for the checking tool may need to get hammered out but should be fine in principle.
cuda.bindingsABI stability #1030yangcal commentedon Nov 17, 2026
RE: tooling, is it possible to build the checking tool in the generator and each project can opt in during binding generation? (I think we should develop the tool just once and shared across teams)