refactor(cuda.core): narrow Buffer.from_handle to Buffer-only (R3)

Per Leo's review on PR #1775 (_buffer.pyx:135), make
Buffer.from_handle a @staticmethod that always returns Buffer.
Subclass-aware construction stays available via the private
@classmethod Buffer._init, which is what Leo asked for ("use a
private method for handling subclasses for now").

ManagedBuffer gains its own @classmethod from_handle that wraps
cls._init, so user-facing call sites like
ManagedBuffer.from_handle(ptr, size, owner=plain) continue to work
unchanged. The narrowly-scoped subclass factory is on the subclass
itself, not bolted onto Buffer's public surface.

This addresses R3's spirit: cuda.core's public APIs no longer
advertise generic subclass-construction support that conflicts
with the broader subclassing story tracked in #750 / #1989.

No test changes; behavior preserved.

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

Author: rparolin

cuda_core/cuda/core/_memory/_buffer.pyx

@@ -131,9 +131,8 @@ cdef class Buffer:
         # Must not serialize the parent's stream!
         return Buffer._reduce_helper, (self.memory_resource, self.get_ipc_descriptor())
 
-    @classmethod
+    @staticmethod
     def from_handle(
-        cls,
         ptr: DevicePointerT, size_t size, mr: MemoryResource | None = None,
         owner: object | None = None,
     ) -> Buffer:
@@ -159,11 +158,8 @@ cdef class Buffer:
         When neither ``mr`` nor ``owner`` is specified, this creates a
         non-owning reference.  The pointer will NOT be freed when the
         :class:`Buffer` is closed or garbage collected.
-
-        Subclasses inherit this method via :meth:`Buffer._init`, so e.g.
-        ``ManagedBuffer.from_handle(ptr, size)`` returns a ``ManagedBuffer``.
         """
-        return cls._init(ptr, size, mr=mr, owner=owner)
+        return Buffer._init(ptr, size, mr=mr, owner=owner)
 
     @classmethod
     def from_ipc_descriptor(

cuda_core/cuda/core/_memory/_managed_buffer.py

@@ -12,6 +12,7 @@
 from cuda.core._utils.cuda_utils import driver, handle_return
 
 if TYPE_CHECKING:
+    from cuda.core._memory._buffer import MemoryResource
     from cuda.core._stream import Stream
     from cuda.core.graph import GraphBuilder
 
@@ -101,9 +102,7 @@ class ManagedBuffer(Buffer):
     """Managed (unified) memory buffer with a property-style advice API.
 
     Returned by :meth:`ManagedMemoryResource.allocate`, or wrap an
-    existing managed-memory pointer with :meth:`Buffer.from_handle`
-    (which dispatches by class — ``ManagedBuffer.from_handle(...)``
-    returns a ``ManagedBuffer``).
+    existing managed-memory pointer with :meth:`ManagedBuffer.from_handle`.
 
     Examples
     --------
@@ -121,6 +120,35 @@ class ManagedBuffer(Buffer):
     advice.
     """
 
+    @classmethod
+    def from_handle(
+        cls,
+        ptr,
+        size: int,
+        mr: MemoryResource | None = None,
+        owner: object | None = None,
+    ) -> ManagedBuffer:
+        """Wrap an existing managed-memory pointer in a :class:`ManagedBuffer`.
+
+        Use this when you have an externally-allocated managed pointer
+        and want the property-style advice API (:attr:`read_mostly`,
+        :attr:`preferred_location`, :attr:`accessed_by`).
+
+        Parameters
+        ----------
+        ptr : :obj:`~_memory.DevicePointerT`
+            Pointer to a managed allocation.
+        size : int
+            Allocation size in bytes.
+        mr : :obj:`~_memory.MemoryResource`, optional
+            Memory resource that owns ``ptr``. When provided, its
+            ``deallocate`` is called when the buffer is closed.
+        owner : object, optional
+            An object that keeps the underlying allocation alive.
+            ``owner`` and ``mr`` cannot both be specified.
+        """
+        return cls._init(ptr, size, mr=mr, owner=owner)
+
     @property
     def read_mostly(self) -> bool:
         """Whether ``set_read_mostly`` advice is currently applied."""