cuda.core: satisfy pre-commit (cython-lint, stubs, formatting)

- Drop unused `intptr_t` cimports in _mipmapped_array.pyx / _surface.pyx
  (flagged by cython-lint; the handle ints now go through as_intptr).
- Regenerate the .pyi stubs (stubgen-pyx) to match the texture/surface .pyx
  after the resource-handle + copy-API changes.
- isort/ruff-format fixups (cuda.core.textures import ordering, etc.).

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

Author: rparolin

cuda_core/cuda/core/__init__.py

@@ -113,10 +113,9 @@ class _PatchedProperty(metaclass=_PatchedPropMeta):
 # Texture/surface types live under the cuda.core.textures namespace (not the
 # flat cuda.core namespace); import the subpackage so it is available as
 # `cuda.core.textures` after `import cuda.core`.
-import cuda.core.textures
-
 # Must come after the cuda.core._* extension imports above: loading graph
 # earlier interacts badly with the merged-wheel __path__ rewrite and leaves
 # Graph/GraphBuilder/GraphCompleteOptions/GraphDebugPrintOptions missing from
 # cuda.core.graph.
 import cuda.core.graph
+import cuda.core.textures

cuda_core/cuda/core/_array.pyi

@@ -44,7 +44,13 @@ class CUDAArray:
     """
 
     def close(self):
-        """Destroy the underlying ``CUarray`` if owned by this object."""
+        """Release this object's reference to the underlying ``CUarray``.
+
+        Destruction (``cuArrayDestroy``) happens via the handle's deleter when
+        the last reference is dropped; for a non-owning handle (graphics interop
+        or a mipmap-level view) nothing is destroyed. Idempotent: a second call
+        (or destruction after ``close()``) is a no-op.
+        """
 
     def __init__(self, *args, **kwargs):
         ...
@@ -77,9 +83,9 @@ class CUDAArray:
         """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.
+        where the array is owned by the graphics API. With ``owning=False`` the
+        underlying ``CUarray`` is never destroyed by this object. Shape, format,
+        and channel count are queried from the driver.
         """
 
     @property
@@ -149,9 +155,6 @@ class CUDAArray:
     def size_bytes(self):
         """Total bytes of array storage (``prod(shape) * element_size``)."""
 
-    def __dealloc__(self):
-        ...
-
     def __enter__(self):
         ...
 

cuda_core/cuda/core/_mipmapped_array.pyi

@@ -17,10 +17,12 @@ class MipmappedArray:
     """
 
     def close(self):
-        """Destroy the underlying ``CUmipmappedArray`` if owned.
+        """Release this object's reference to the underlying ``CUmipmappedArray``.
 
-        After ``close()`` any level :class:`CUDAArray` returned by :meth:`get_level`
-        becomes invalid; callers must not access them.
+        Destruction (``cuMipmappedArrayDestroy``) happens via the handle's
+        deleter when the last reference is dropped. A level :class:`CUDAArray`
+        from :meth:`get_level` holds its own reference to this mipmap's storage,
+        so it stays valid until both it and this object are released. Idempotent.
         """
 
     def __init__(self, *args, **kwargs):
@@ -99,9 +101,6 @@ class MipmappedArray:
     def device(self):
         """The :class:`Device` this mipmap was allocated on."""
 
-    def __dealloc__(self):
-        ...
-
     def __enter__(self):
         ...
 

cuda_core/cuda/core/_mipmapped_array.pyx

@@ -4,7 +4,6 @@
 
 from __future__ import annotations
 
-from libc.stdint cimport intptr_t
 from libc.string cimport memset
 
 from cuda.bindings cimport cydriver

cuda_core/cuda/core/_resource_handles.pyi

@@ -19,4 +19,8 @@ NvrtcProgramHandle = shared_ptr
 NvvmProgramHandle = shared_ptr
 NvJitLinkHandle = shared_ptr
 CuLinkHandle = shared_ptr
-FileDescriptorHandle = shared_ptr
+FileDescriptorHandle = shared_ptr
+ArrayHandle = shared_ptr
+MipmappedArrayHandle = shared_ptr
+TexObjectHandle = shared_ptr
+SurfObjectHandle = shared_ptr

cuda_core/cuda/core/_surface.pyi

@@ -19,7 +19,12 @@ class SurfaceObject:
     """
 
     def close(self):
-        """Destroy the underlying ``CUsurfObject``."""
+        """Release this object's reference to the underlying ``CUsurfObject``.
+
+        Destruction (``cuSurfObjectDestroy``) and release of the backing array
+        happen via the handle's deleter when the last reference is dropped.
+        Idempotent.
+        """
 
     def __init__(self, *args, **kwargs):
         ...
@@ -55,9 +60,6 @@ class SurfaceObject:
     def device(self):
         ...
 
-    def __dealloc__(self):
-        ...
-
     def __enter__(self):
         ...
 

cuda_core/cuda/core/_surface.pyx

@@ -4,7 +4,6 @@
 
 from __future__ import annotations
 
-from libc.stdint cimport intptr_t
 from libc.string cimport memset
 
 from cuda.bindings cimport cydriver

cuda_core/cuda/core/_texture.pyi

@@ -209,7 +209,12 @@ class TextureObject:
     """
 
     def close(self):
-        """Destroy the underlying ``CUtexObject``."""
+        """Release this object's reference to the underlying ``CUtexObject``.
+
+        Destruction (``cuTexObjectDestroy``) and release of the backing resource
+        happen via the handle's deleter when the last reference is dropped.
+        Idempotent.
+        """
 
     def __init__(self, *args, **kwargs):
         ...
@@ -240,9 +245,6 @@ class TextureObject:
     def device(self):
         ...
 
-    def __dealloc__(self):
-        ...
-
     def __enter__(self):
         ...
 

cuda_core/tests/test_texture_surface.py

@@ -620,9 +620,7 @@ def test_texture_surface_close_is_idempotent(init_cuda):
     assert arr.handle == 0
     arr.close()  # second close must not raise
 
-    mip = MipmappedArray.from_descriptor(
-        shape=(8, 8), format=ArrayFormat.UINT8, num_channels=1, num_levels=2
-    )
+    mip = MipmappedArray.from_descriptor(shape=(8, 8), format=ArrayFormat.UINT8, num_channels=1, num_levels=2)
     mip.close()
     assert mip.handle == 0
     mip.close()