[EPIC] RFC: `cuda` namespace cleanup

[leofang]

Impact

Very little, except for those accessing __version__ from the cuda namespace, via, say,

from cuda import __version__

We'll offer a fallback (that would raise a warning) before the transition concludes. Semantically, this will be equivalent to

from cuda.bindings import __version__

after the transition, so we do not expect to break any existing code. See below for further details.

Context

1. cuda-python is currently tightly coupled to CTK releases (including its versioning scheme) which is problematic as we move higher in the stack (say by offering pythonic CUDA constructs that can be used across CTK major releases).
2. We want to add more features and functionalities as modules under cuda, each of which is potentially separately versioned.
3. The top-level module cuda is not yet a namespace module.
4. The name cuda.cuda for the CUDA driver API bindings is confusing (why is “cuda” = driver?)

Existing module layout

• driver:
  • cuda.cuda (Python)
  • cuda.ccuda (Cython)
  • cuda._cuda.ccuda (internal)
• runtime:
  • cuda.cudart (Python)
  • cuda.ccudart (Cython)
  • cuda._lib.ccudart.ccudart (internal)
• NVRTC:
  • cuda.nvrtc (Python)
  • cuda.cnvrtc (Cython)
  • cuda._cuda.cnvrtc (internal)
• others:
  • cuda/__init__.py (only defines __version__ and nothing else)

Solution

This proposal solves the problem by requiring the following changes to support namespace packages:

1. Remove cuda/__init__.py
2. Move actual code from the listed modules above (see “Existing module layout”) to the new place below (see “New module layout”).
3. Raise compile-time/run-time deprecation warnings in the existing modules listed above (see the “Transition plan” section below).
4. Publish new namespace packages as they are implemented.

New module layout

• bindings:
  • driver:
    • cuda.bindings.driver (Python)
    • cuda.bindings.cydriver (Cython)
    • cuda.bindings._internal.driver (internal)
  • runtime:
    • cuda.bindings.runtime (Python)
    • cuda.bindings.cyruntime (Cython)
    • cuda.bindings._internal.runtime (internal)
  • NVRTC:
    • cuda.bindings.nvrtc (Python)
    • cuda.bindings.cynvrtc (Cython)
    • cuda.bindings._internal.nvrtc (internal)
  • nvJitLink (future):
    • cuda.bindings.nvjitlink (Python)
    • cuda.bindings.cynvjitlink (Cython)
    • cuda.bindings._internal.nvjitlink (internal)
  • libnvvm (future):
    • cuda.bindings.libnvvm (Python)
    • cuda.bindings.cylibnvvm (Cython)
    • cuda.bindings._internal.libnvvm (internal)

Transition plan

The transition to namespace packages is meant to be a non-breaking change, at least within the CUDA minor releases.

• CUDA 12.x (12.7?)
  • Raise a compile-time deprecation warning for users cimport’ing the Cython modules:
    • cuda.ccuda (driver)
      • internally: from cuda.bindings.driver cimport *
    • cuda.ccudart (runtime)
      • internally: from cuda.bindings.runtime cimport *
    • cuda.cnvrtc (NVRTC)
      • internally: from cuda.bindings.nvrtc cimport *
  • Raise a run-time DeprecationWarning for users import’ing the Python modules:
    • cuda.cuda (driver)
      • internally: from cuda.bindings.driver import *
    • cuda.cudart (runtime)
      • internally: from cuda.bindings.runtime import *
    • cuda.nvrtc (NVRTC)
      • internally: from cuda.bindings.nvrtc import *
  • The internal modules are not supposed to be used by anyone anyway, remove them right away.
    • cuda._cuda
    • cuda._lib
  • Add a migration guide to the documentation to teach about the new modules
  • Add release note entries to warn about the upcoming change
  • Post a new announcement to NVIDIA/cuda-python Discussion
  • Work with major impacted projects to start early migration:
    • Cython module users: RAPIDS, CuPy (link)
    • Python module users: Numba, ??????
• CUDA 13.0
  • Turn the DeprecationWarning to user-visible UserWarning
• CUDA 13.x
  • Remove the deprecated Cython & Python modules (at this point they don’t contain actual code, as they are just “trampolines”
    • cuda.ccuda (driver)
    • cuda.ccudart (runtime)
    • cuda.cnvrtc (NVRTC)
    • cuda.cuda (driver)
    • cuda.cudart (runtime)
    • cuda.nvrtc (NVRTC)

[leofang]

(Updated issue description.)