cuda.core: fix lint/mypy after merging main; add generated .pyi stubs

Post-merge cleanup so pre-commit.ci passes on the texture/surface stack:

- Switch ReadMode/AddressMode/FilterMode/ArrayFormat to `from enum import
  IntEnum` so stubgen-pyx preserves the IntEnum base in the generated stubs
  (qualified `enum.IntEnum` was dropped, making members infer as `int` and
  failing mypy assignment checks).
- Annotate TextureDescriptor.border_color as `tuple[float, ...] | None`
  (disallow_any_generics flagged the bare `tuple`).
- Prefix unused pyglet event-handler args with `_` (ARG001) and lowercase
  in-function locals (N806) across the GL interop examples; drop dead
  pre-try buffer inits in texture_sample.main (F841).
- Commit the auto-generated .pyi stubs for the new _array/_texture/_surface/
  _mipmapped_array modules.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: rparolin

cuda_core/cuda/core/__init__.py

@@ -69,6 +69,7 @@ class _PatchedProperty(metaclass=_PatchedPropMeta):
 
 
 from cuda.core import checkpoint, system, utils
+from cuda.core._array import ArrayFormat, CUDAArray
 from cuda.core._context import Context, ContextOptions
 from cuda.core._device import Device
 from cuda.core._device_resources import (
@@ -78,17 +79,6 @@ class _PatchedProperty(metaclass=_PatchedPropMeta):
     WorkqueueResource,
     WorkqueueResourceOptions,
 )
-from cuda.core._array import CUDAArray, ArrayFormat
-from cuda.core._mipmapped_array import MipmappedArray
-from cuda.core._texture import (
-    AddressMode,
-    FilterMode,
-    ReadMode,
-    ResourceDescriptor,
-    TextureDescriptor,
-    TextureObject,
-)
-from cuda.core._surface import SurfaceObject
 from cuda.core._event import Event, EventOptions
 from cuda.core._graphics import GraphicsResource
 from cuda.core._host import Host
@@ -110,6 +100,7 @@ class _PatchedProperty(metaclass=_PatchedPropMeta):
     VirtualMemoryResource,
     VirtualMemoryResourceOptions,
 )
+from cuda.core._mipmapped_array import MipmappedArray
 from cuda.core._module import Kernel, ObjectCode
 from cuda.core._program import Program, ProgramOptions
 from cuda.core._stream import (
@@ -118,7 +109,16 @@ class _PatchedProperty(metaclass=_PatchedPropMeta):
     Stream,
     StreamOptions,
 )
+from cuda.core._surface import SurfaceObject
 from cuda.core._tensor_map import TensorMapDescriptor, TensorMapDescriptorOptions
+from cuda.core._texture import (
+    AddressMode,
+    FilterMode,
+    ReadMode,
+    ResourceDescriptor,
+    TextureDescriptor,
+    TextureObject,
+)
 
 # isort: split
 # Must come after the cuda.core._* extension imports above: loading graph

cuda_core/cuda/core/_array.pyi

@@ -0,0 +1,148 @@
+# This file was generated by stubgen-pyx v0.2.6 from cuda_core/cuda/core/_array.pyx
+
+from __future__ import annotations
+
+from enum import IntEnum
+
+from cuda.bindings import cydriver
+
+
+class ArrayFormat(IntEnum):
+    """Element format for a :class:`CUDAArray` allocation.
+
+    Mirrors ``CUarray_format`` from the CUDA driver API.
+    """
+    UINT8 = cydriver.CU_AD_FORMAT_UNSIGNED_INT8
+    UINT16 = cydriver.CU_AD_FORMAT_UNSIGNED_INT16
+    UINT32 = cydriver.CU_AD_FORMAT_UNSIGNED_INT32
+    INT8 = cydriver.CU_AD_FORMAT_SIGNED_INT8
+    INT16 = cydriver.CU_AD_FORMAT_SIGNED_INT16
+    INT32 = cydriver.CU_AD_FORMAT_SIGNED_INT32
+    FLOAT16 = cydriver.CU_AD_FORMAT_HALF
+    FLOAT32 = cydriver.CU_AD_FORMAT_FLOAT
+
+class CUDAArray:
+    """An opaque, hardware-laid-out GPU allocation for texture/surface access.
+
+    Distinct from :class:`Buffer`: a ``CUarray`` has no exposed device pointer
+    and can only be accessed from kernels through a :class:`TextureObject` or
+    :class:`SurfaceObject`. Its memory layout is chosen by the driver for 2D/3D
+    spatial locality.
+
+    Construct via :meth:`from_descriptor`. Only plain 1D/2D/3D allocations are
+    supported in this initial version; layered/cubemap/sparse variants will
+    follow once their shape semantics are settled.
+    """
+
+    def close(self):
+        """Destroy the underlying ``CUarray`` if owned by this object."""
+
+    def __init__(self, *args, **kwargs):
+        ...
+
+    @classmethod
+    def from_descriptor(cls, *, shape, format, num_channels, surface_load_store=False):
+        """Allocate a new CUDA array.
+
+        Parameters
+        ----------
+        shape : tuple of int
+            ``(width,)``, ``(width, height)``, or ``(width, height, depth)``
+            in elements.
+        format : ArrayFormat
+            Element format.
+        num_channels : int
+            Channels per element. Must be 1, 2, or 4.
+        surface_load_store : bool
+            If True, allocate with ``CUDA_ARRAY3D_SURFACE_LDST`` so the array
+            can be bound as a :class:`SurfaceObject` for kernel-side writes.
+            Default False.
+
+        Returns
+        -------
+        CUDAArray
+        """
+
+    @classmethod
+    def _from_handle(cls, handle: int, owning: bool, *, device_id=None):
+        """Wrap an externally-allocated ``CUarray``.
+
+        Intended for graphics interop (``cuGraphicsSubResourceGetMappedArray``)
+        where the array is owned by the graphics API. With ``owning=False``,
+        :meth:`close` and ``__dealloc__`` will not free the handle. Shape,
+        format, and channel count are queried from the driver.
+        """
+
+    @property
+    def handle(self):
+        """The underlying ``CUarray`` as an integer."""
+
+    @property
+    def shape(self):
+        """Allocation shape, in elements."""
+
+    @property
+    def format(self):
+        """The element :class:`ArrayFormat`."""
+
+    @property
+    def num_channels(self):
+        """Channels per element (1, 2, or 4)."""
+
+    @property
+    def element_size(self):
+        """Bytes per element (format size * channels)."""
+
+    @property
+    def device(self):
+        """The :class:`Device` this array was allocated on."""
+
+    @property
+    def is_surface_load_store(self):
+        """True if this array was created with ``CUDA_ARRAY3D_SURFACE_LDST``
+        and can be bound as a :class:`SurfaceObject`."""
+
+    def _extent_bytes(self):
+        """Return (width_bytes, height, depth) for cuMemcpy3D, with height/depth
+        normalized to >=1 for lower-rank arrays."""
+
+    def copy_from(self, src, *, stream):
+        """Copy a full-array's worth of data into this array.
+
+        Parameters
+        ----------
+        src : Buffer or buffer-protocol object
+            Source data. Must contain at least ``self.size_bytes`` bytes
+            of contiguous data.
+        stream : Stream
+            Stream to issue the copy on.
+        """
+
+    def copy_to(self, dst, *, stream):
+        """Copy a full-array's worth of data out of this array.
+
+        Parameters
+        ----------
+        dst : Buffer or writable buffer-protocol object
+            Destination. Must have at least ``self.size_bytes`` bytes of
+            writable, contiguous space.
+        stream : Stream
+            Stream to issue the copy on.
+        """
+
+    @property
+    def size_bytes(self):
+        """Total bytes of array storage (``prod(shape) * element_size``)."""
+
+    def __dealloc__(self):
+        ...
+
+    def __enter__(self):
+        ...
+
+    def __exit__(self, exc_type, exc, tb):
+        ...
+
+    def __repr__(self):
+        ...
+_FORMAT_ELEM_SIZE = {int(ArrayFormat.UINT8): 1, int(ArrayFormat.INT8): 1, int(ArrayFormat.UINT16): 2, int(ArrayFormat.INT16): 2, int(ArrayFormat.FLOAT16): 2, int(ArrayFormat.UINT32): 4, int(ArrayFormat.INT32): 4, int(ArrayFormat.FLOAT32): 4}

cuda_core/cuda/core/_array.pyx

@@ -17,10 +17,10 @@ from cuda.core._utils.cuda_utils cimport (
     _get_current_device_id,
 )
 
-import enum
+from enum import IntEnum
 
 
-class ArrayFormat(enum.IntEnum):
+class ArrayFormat(IntEnum):
     """Element format for a :class:`CUDAArray` allocation.
 
     Mirrors ``CUarray_format`` from the CUDA driver API.

cuda_core/cuda/core/_mipmapped_array.pyi

@@ -0,0 +1,112 @@
+# This file was generated by stubgen-pyx v0.2.6 from cuda_core/cuda/core/_mipmapped_array.pyx
+
+from __future__ import annotations
+
+
+class MipmappedArray:
+    """A mipmapped CUDA array for texture/surface access across levels.
+
+    Wraps ``CUmipmappedArray``. Each mip level is a distinct, hardware-laid-out
+    allocation accessible only via a :class:`TextureObject` (or by retrieving
+    the level's :class:`CUDAArray` and binding it as a :class:`SurfaceObject`).
+    Destroying the :class:`MipmappedArray` destroys all level arrays
+    implicitly, so the :class:`CUDAArray` instances returned by :meth:`get_level`
+    are non-owning and hold a strong reference back to their parent.
+
+    Construct via :meth:`from_descriptor`.
+    """
+
+    def close(self):
+        """Destroy the underlying ``CUmipmappedArray`` if owned.
+
+        After ``close()`` any level :class:`CUDAArray` returned by :meth:`get_level`
+        becomes invalid; callers must not access them.
+        """
+
+    def __init__(self, *args, **kwargs):
+        ...
+
+    @classmethod
+    def from_descriptor(cls, *, shape, format, num_channels, num_levels, surface_load_store=False):
+        """Allocate a new mipmapped CUDA array.
+
+        Parameters
+        ----------
+        shape : tuple of int
+            ``(width,)``, ``(width, height)``, or ``(width, height, depth)``
+            in elements, for the base (level 0) mip.
+        format : ArrayFormat
+            Element format.
+        num_channels : int
+            Channels per element. Must be 1, 2, or 4.
+        num_levels : int
+            Number of mip levels to allocate; must be >= 1. The driver caps
+            this at the log2 of the largest dimension; passing a larger value
+            yields a driver error.
+        surface_load_store : bool
+            If True, allocate with ``CUDA_ARRAY3D_SURFACE_LDST`` so individual
+            levels (obtained via :meth:`get_level`) can be bound as
+            :class:`SurfaceObject` for kernel-side writes. Default False.
+
+        Returns
+        -------
+        MipmappedArray
+        """
+
+    def get_level(self, level):
+        """Return a non-owning :class:`CUDAArray` view of the given mip level.
+
+        Parameters
+        ----------
+        level : int
+            Mip level index in ``[0, num_levels)``.
+
+        Returns
+        -------
+        CUDAArray
+            A non-owning :class:`CUDAArray` wrapping the level's ``CUarray``.
+            The :class:`MipmappedArray` is kept alive for the lifetime of the
+            returned :class:`CUDAArray`; the underlying storage is released only
+            when this :class:`MipmappedArray` is destroyed.
+        """
+
+    @property
+    def handle(self):
+        """The underlying ``CUmipmappedArray`` as an integer."""
+
+    @property
+    def shape(self):
+        """Base-level (level 0) allocation shape, in elements."""
+
+    @property
+    def format(self):
+        """The element :class:`ArrayFormat`."""
+
+    @property
+    def num_channels(self):
+        """Channels per element (1, 2, or 4)."""
+
+    @property
+    def num_levels(self):
+        """Number of mip levels."""
+
+    @property
+    def is_surface_load_store(self):
+        """True if this mipmap (and each of its levels) was created with
+        ``CUDA_ARRAY3D_SURFACE_LDST`` and can back a :class:`SurfaceObject`."""
+
+    @property
+    def device(self):
+        """The :class:`Device` this mipmap was allocated on."""
+
+    def __dealloc__(self):
+        ...
+
+    def __enter__(self):
+        ...
+
+    def __exit__(self, exc_type, exc, tb):
+        ...
+
+    def __repr__(self):
+        ...

cuda_core/cuda/core/_surface.pyi

@@ -0,0 +1,68 @@
+# This file was generated by stubgen-pyx v0.2.6 from cuda_core/cuda/core/_surface.pyx
+
+from __future__ import annotations
+
+
+class SurfaceObject:
+    """A bindless surface handle for kernel-side typed load/store.
+
+    Wraps ``cuSurfObjectCreate``. Unlike a :class:`TextureObject`, a surface
+    has no sampling state (no filtering, no addressing modes, no normalization);
+    kernels read and write through it using integer pixel coordinates.
+
+    The backing :class:`CUDAArray` must have been created with
+    ``surface_load_store=True`` and is kept alive for the lifetime of this
+    object to prevent dangling handles.
+
+    Construct via :meth:`from_array` or :meth:`from_descriptor`. Passes to
+    kernels as a 64-bit handle (via the ``handle`` property).
+    """
+
+    def close(self):
+        """Destroy the underlying ``CUsurfObject``."""
+
+    def __init__(self, *args, **kwargs):
+        ...
+
+    @classmethod
+    def from_array(cls, array):
+        """Create a surface object directly from an :class:`CUDAArray`.
+
+        The array must have been created with ``surface_load_store=True``.
+        """
+
+    @classmethod
+    def from_descriptor(cls, *, resource):
+        """Create a surface object from a :class:`ResourceDescriptor`.
+
+        Parameters
+        ----------
+        resource : ResourceDescriptor
+            Must wrap an :class:`CUDAArray` allocated with
+            ``surface_load_store=True``. Linear/pitch2d resources are not
+            valid surface backings.
+        """
+
+    @property
+    def handle(self):
+        """The underlying ``CUsurfObject`` as an integer (64-bit kernel arg)."""
+
+    @property
+    def resource(self):
+        """The :class:`ResourceDescriptor` this surface was built from."""
+
+    @property
+    def device(self):
+        ...
+
+    def __dealloc__(self):
+        ...
+
+    def __enter__(self):
+        ...
+
+    def __exit__(self, exc_type, exc, tb):
+        ...
+
+    def __repr__(self):
+        ...