ctypes-dlpack 0.1.0__py3-none-any.whl

ctypes_dlpack/__init__.py

@@ -0,0 +1,61 @@
+from ._c_api import (
+    DLPACK_FLAG_BITMASK_IS_COPIED,
+    DLPACK_FLAG_BITMASK_IS_SUBBYTE_TYPE_PADDED,
+    DLPACK_FLAG_BITMASK_READ_ONLY,
+    DLPACK_MAJOR_VERSION,
+    DLPACK_MINOR_VERSION,
+    DLDataType,
+    DLDataTypeCode,
+    DLDevice,
+    DLDeviceType,
+    DLManagedTensor,
+    DLManagedTensorVersioned,
+    DLPackCurrentWorkStream,
+    DLPackDLTensorFromPyObjectNoSync,
+    DLPackExchangeAPI,
+    DLPackExchangeAPIHeader,
+    DLPackManagedTensorAllocator,
+    DLPackManagedTensorFromPyObjectNoSync,
+    DLPackManagedTensorToPyObjectNoSync,
+    DLPackVersion,
+    DLTensor,
+)
+from ._dlpack import DLPackArray, array_as_dlpack
+
+
+__version__ = "0.1.0"
+
+
+__all__ = [
+    "DLPACK_FLAG_BITMASK_IS_COPIED",
+    "DLPACK_FLAG_BITMASK_IS_SUBBYTE_TYPE_PADDED",
+    "DLPACK_FLAG_BITMASK_READ_ONLY",
+    "DLPACK_MAJOR_VERSION",
+    "DLPACK_MINOR_VERSION",
+    "DLPackManagedTensorAllocator",
+    "DLPackManagedTensorFromPyObjectNoSync",
+    "DLPackDLTensorFromPyObjectNoSync",
+    "DLPackCurrentWorkStream",
+    "DLPackManagedTensorToPyObjectNoSync",
+    "DLDeviceType",
+    "DLDataTypeCode",
+    "DLPackVersion",
+    "DLDevice",
+    "DLDataType",
+    "DLTensor",
+    "DLManagedTensor",
+    "DLManagedTensorVersioned",
+    "DLPackExchangeAPIHeader",
+    "DLPackExchangeAPI",
+    "DLPackArray",
+    "array_as_dlpack",
+]
+
+
+for _name in __all__:
+    _value = globals()[_name]
+    if getattr(_value, "__module__", None) == "ctypes_dlpack._c_api":
+        _value.__module__ = __name__
+
+
+del _name, _value

ctypes_dlpack/_c_api.py

@@ -0,0 +1,210 @@
+# ruff: noqa
+import ctypes
+
+DLPACK_FLAG_BITMASK_IS_COPIED = 1 << 1
+DLPACK_FLAG_BITMASK_IS_SUBBYTE_TYPE_PADDED = 1 << 2
+DLPACK_FLAG_BITMASK_READ_ONLY = 1 << 0
+DLPACK_MAJOR_VERSION = 1
+DLPACK_MINOR_VERSION = 3
+
+
+class _EnumType(type(ctypes.c_int32)):
+    def __new__(metacls, name, bases, namespace):
+        if "_members_" not in namespace:
+            members = {}
+            for key, value in namespace.items():
+                if not key.startswith("_"):
+                    members[key] = value
+            namespace["_members_"] = members
+        else:
+            members = namespace["_members_"]
+
+        namespace["_reverse_map_"] = {v: k for k, v in members.items()}
+        return type(ctypes.c_int32).__new__(metacls, name, bases, namespace)
+
+    def __repr__(self):
+        return f"<Enum {self.__name__}>"
+
+
+class _Enum(ctypes.c_int32, metaclass=_EnumType):
+    _members_ = {}
+
+    def __repr__(self):
+        value_name = self._reverse_map_.get(self.value, str(self.value))
+        return f"{self.__class__.__name__}.{value_name}"
+
+    def __eq__(self, other):
+        if isinstance(other, int):
+            return self.value == other
+        if type(self) is type(other):
+            return self.value == other.value
+        return NotImplemented
+
+    def __hash__(self):
+        return hash(self.value)
+
+
+class DLDeviceType(_Enum):
+    pass
+    kDLCPU = 1
+    kDLCUDA = 2
+    kDLCUDAHost = 3
+    kDLOpenCL = 4
+    kDLVulkan = 7
+    kDLMetal = 8
+    kDLVPI = 9
+    kDLROCM = 10
+    kDLROCMHost = 11
+    kDLExtDev = 12
+    kDLCUDAManaged = 13
+    kDLOneAPI = 14
+    kDLWebGPU = 15
+    kDLHexagon = 16
+    kDLMAIA = 17
+    kDLTrn = 18
+
+
+class DLDataTypeCode(_Enum):
+    pass
+    kDLInt = 0
+    kDLUInt = 1
+    kDLFloat = 2
+    kDLOpaqueHandle = 3
+    kDLBfloat = 4
+    kDLComplex = 5
+    kDLBool = 6
+    kDLFloat8_e3m4 = 7
+    kDLFloat8_e4m3 = 8
+    kDLFloat8_e4m3b11fnuz = 9
+    kDLFloat8_e4m3fn = 10
+    kDLFloat8_e4m3fnuz = 11
+    kDLFloat8_e5m2 = 12
+    kDLFloat8_e5m2fnuz = 13
+    kDLFloat8_e8m0fnu = 14
+    kDLFloat6_e2m3fn = 15
+    kDLFloat6_e3m2fn = 16
+    kDLFloat4_e2m1fn = 17
+
+
+class DLPackVersion(ctypes.Structure):
+    pass
+
+
+class DLDevice(ctypes.Structure):
+    pass
+
+
+class DLDataType(ctypes.Structure):
+    pass
+
+
+class DLTensor(ctypes.Structure):
+    pass
+
+
+class DLManagedTensor(ctypes.Structure):
+    pass
+
+
+class DLManagedTensorVersioned(ctypes.Structure):
+    pass
+
+
+class DLPackExchangeAPIHeader(ctypes.Structure):
+    pass
+
+
+class DLPackExchangeAPI(ctypes.Structure):
+    pass
+
+
+DLPackManagedTensorAllocator = ctypes.CFUNCTYPE(
+    ctypes.c_int,
+    ctypes.POINTER(DLTensor),
+    ctypes.POINTER(ctypes.POINTER(DLManagedTensorVersioned)),
+    ctypes.c_void_p,
+    ctypes.CFUNCTYPE(None, ctypes.c_void_p, ctypes.c_char_p, ctypes.c_char_p),
+)
+
+
+DLPackManagedTensorFromPyObjectNoSync = ctypes.CFUNCTYPE(
+    ctypes.c_int,
+    ctypes.c_void_p,
+    ctypes.POINTER(ctypes.POINTER(DLManagedTensorVersioned)),
+)
+
+
+DLPackDLTensorFromPyObjectNoSync = ctypes.CFUNCTYPE(
+    ctypes.c_int,
+    ctypes.c_void_p,
+    ctypes.POINTER(DLTensor),
+)
+
+
+DLPackCurrentWorkStream = ctypes.CFUNCTYPE(
+    ctypes.c_int,
+    DLDeviceType,
+    ctypes.c_int32,
+    ctypes.POINTER(ctypes.c_void_p),
+)
+
+
+DLPackManagedTensorToPyObjectNoSync = ctypes.CFUNCTYPE(
+    ctypes.c_int,
+    ctypes.POINTER(DLManagedTensorVersioned),
+    ctypes.POINTER(ctypes.c_void_p),
+)
+
+DLPackVersion._fields_ = [
+    ("major", ctypes.c_uint32),
+    ("minor", ctypes.c_uint32),
+]
+
+DLDevice._fields_ = [
+    ("device_type", DLDeviceType),
+    ("device_id", ctypes.c_int32),
+]
+
+DLDataType._fields_ = [
+    ("code", ctypes.c_uint8),
+    ("bits", ctypes.c_uint8),
+    ("lanes", ctypes.c_uint16),
+]
+
+DLTensor._fields_ = [
+    ("data", ctypes.c_void_p),
+    ("device", DLDevice),
+    ("ndim", ctypes.c_int32),
+    ("dtype", DLDataType),
+    ("shape", ctypes.POINTER(ctypes.c_int64)),
+    ("strides", ctypes.POINTER(ctypes.c_int64)),
+    ("byte_offset", ctypes.c_uint64),
+]
+
+DLManagedTensor._fields_ = [
+    ("dl_tensor", DLTensor),
+    ("manager_ctx", ctypes.c_void_p),
+    ("deleter", ctypes.CFUNCTYPE(None, ctypes.POINTER(DLManagedTensor))),
+]
+
+DLManagedTensorVersioned._fields_ = [
+    ("version", DLPackVersion),
+    ("manager_ctx", ctypes.c_void_p),
+    ("deleter", ctypes.CFUNCTYPE(None, ctypes.POINTER(DLManagedTensorVersioned))),
+    ("flags", ctypes.c_uint64),
+    ("dl_tensor", DLTensor),
+]
+
+DLPackExchangeAPIHeader._fields_ = [
+    ("version", DLPackVersion),
+    ("prev_api", ctypes.POINTER(DLPackExchangeAPIHeader)),
+]
+
+DLPackExchangeAPI._fields_ = [
+    ("header", DLPackExchangeAPIHeader),
+    ("managed_tensor_allocator", DLPackManagedTensorAllocator),
+    ("managed_tensor_from_py_object_no_sync", DLPackManagedTensorFromPyObjectNoSync),
+    ("managed_tensor_to_py_object_no_sync", DLPackManagedTensorToPyObjectNoSync),
+    ("dltensor_from_py_object_no_sync", DLPackDLTensorFromPyObjectNoSync),
+    ("current_work_stream", DLPackCurrentWorkStream),
+]

ctypes_dlpack/_dlpack.py

@@ -0,0 +1,524 @@
+import ctypes
+
+from ._c_api import (
+    DLDevice,
+    DLManagedTensor,
+    DLManagedTensorVersioned,
+    DLPackVersion,
+    DLTensor,
+)
+
+
+PYTHON_API = ctypes.pythonapi
+
+# Configure Python C-API entry points once, then reuse them from hot paths.
+PYTHON_API.PyCapsule_GetPointer.restype = ctypes.c_void_p
+PYTHON_API.PyCapsule_GetPointer.argtypes = [ctypes.py_object, ctypes.c_char_p]
+
+PYTHON_API.PyCapsule_SetName.restype = ctypes.c_int
+PYTHON_API.PyCapsule_SetName.argtypes = [ctypes.py_object, ctypes.c_char_p]
+
+PYTHON_API.PyCapsule_GetName.restype = ctypes.c_char_p
+PYTHON_API.PyCapsule_GetName.argtypes = [ctypes.py_object]
+
+PYTHON_API.PyMem_RawMalloc.restype = ctypes.c_void_p
+PYTHON_API.PyMem_RawMalloc.argtypes = [ctypes.c_size_t]
+
+PYTHON_API.PyMem_RawFree.restype = None
+PYTHON_API.PyMem_RawFree.argtypes = [ctypes.c_void_p]
+
+PYTHON_API.PyCapsule_New.restype = ctypes.py_object
+PYTHON_API.PyCapsule_New.argtypes = [ctypes.c_void_p, ctypes.c_char_p, ctypes.c_void_p]
+
+PYTHON_API.PyErr_Fetch.restype = None
+PYTHON_API.PyErr_Fetch.argtypes = [
+    ctypes.POINTER(ctypes.py_object),
+    ctypes.POINTER(ctypes.py_object),
+    ctypes.POINTER(ctypes.py_object),
+]
+
+PYTHON_API.PyErr_Clear.restype = None
+PYTHON_API.PyErr_Clear.argtypes = []
+
+
+def _fetch_pyerr():
+    """Detach and return the current C-API exception instance, or ``None``.
+
+    ``PyErr_Fetch`` clears the thread-local exception state, so the caller is free to
+    raise a fresh exception without CPython discarding the original one.
+    """
+    etype = ctypes.py_object()
+    evalue = ctypes.py_object()
+    etb = ctypes.py_object()
+    PYTHON_API.PyErr_Fetch(ctypes.byref(etype), ctypes.byref(evalue), ctypes.byref(etb))
+    return evalue.value or None
+
+
+# ``PyCapsule_GetName``/``PyCapsule_GetPointer`` re-bound with a raw ``c_void_p``
+# argument. These are needed from inside ``_versioned_capsule_destructor``:
+# CPython invokes the destructor during ``PyCapsule dealloc`` while the capsule
+# refcount is already 0, so the argument cannot be passed as ``py_object``
+# (which would INCREF then DECREF back to 0, recursively re-triggering
+# ``dealloc``). The raw pointer is obtained from the cached symbol address.
+_PyCapsule_GetName_c_void_p = ctypes.CFUNCTYPE(ctypes.c_char_p, ctypes.c_void_p)(
+    ctypes.cast(PYTHON_API.PyCapsule_GetName, ctypes.c_void_p).value
+)
+
+_PyCapsule_GetPointer_c_void_p = ctypes.CFUNCTYPE(
+    ctypes.c_void_p, ctypes.c_void_p, ctypes.c_char_p
+)(ctypes.cast(PYTHON_API.PyCapsule_GetPointer, ctypes.c_void_p).value)
+
+
+DLPACK_VERSIONED_NAME = b"dltensor_versioned"
+USED_DLPACK_VERSIONED_NAME = b"used_dltensor_versioned"
+DLPACK_NAME = b"dltensor"
+USED_DLPACK_NAME = b"used_dltensor"
+
+
+def _versioned_capsule_destructor(capsule_ptr):
+    """Release the ``DLManagedTensorVersioned`` held by a capsule.
+
+    This is invoked by CPython when the capsule is garbage collected without having
+    been consumed by a ``__dlpack__`` importer (i.e. its name is still
+    ``dltensor_versioned``). Capsules renamed to ``used_dltensor_versioned`` have
+    already been taken over by an importer and are left untouched.
+
+    The argument is a raw ``void*`` (the capsule pointer) rather than
+    ``py_object`` because CPython invokes the destructor during ``dealloc`` with
+    the capsule already at refcount 0: wrapping it as ``py_object`` would INCREF
+    then DECREF it back to 0, recursively re-triggering ``dealloc``.
+    """
+    if not capsule_ptr:
+        return
+
+    name = _PyCapsule_GetName_c_void_p(capsule_ptr)
+    if name != DLPACK_VERSIONED_NAME:
+        # Clear any C-API exception (e.g. set by ``GetName`` on failure)
+        PYTHON_API.PyErr_Clear()
+        return
+
+    ptr = _PyCapsule_GetPointer_c_void_p(capsule_ptr, DLPACK_VERSIONED_NAME)
+    if not ptr:
+        PYTHON_API.PyErr_Clear()
+        return
+
+    versioned_ptr = ctypes.cast(ptr, ctypes.POINTER(DLManagedTensorVersioned))
+    versioned = versioned_ptr.contents
+    if versioned.deleter:
+        versioned.deleter(versioned_ptr)
+
+
+# Keep a reference so the CFUNCTYPE is not garbage-collected while CPython holds
+# the destructor pointer inside the capsule.
+_VERSIONED_CAPSULE_DESTRUCTOR_C = ctypes.CFUNCTYPE(None, ctypes.c_void_p)(
+    _versioned_capsule_destructor
+)
+
+
+def _unversioned_capsule_destructor(capsule_ptr):
+    """Release the ``DLManagedTensor`` held by a legacy capsule.
+
+    See ``_versioned_capsule_destructor`` for why the argument is a raw
+    ``void*`` instead of ``py_object``.
+    """
+    if not capsule_ptr:
+        return
+
+    name = _PyCapsule_GetName_c_void_p(capsule_ptr)
+    if name != DLPACK_NAME:
+        # Clear any C-API exception (see ``_versioned_capsule_destructor``).
+        PYTHON_API.PyErr_Clear()
+        return
+
+    ptr = _PyCapsule_GetPointer_c_void_p(capsule_ptr, DLPACK_NAME)
+    if not ptr:
+        PYTHON_API.PyErr_Clear()
+        return
+
+    unversioned_ptr = ctypes.cast(ptr, ctypes.POINTER(DLManagedTensor))
+    unversioned = unversioned_ptr.contents
+    if unversioned.deleter:
+        unversioned.deleter(unversioned_ptr)
+
+
+# Keep a reference so the CFUNCTYPE is not garbage-collected while CPython holds
+# the destructor pointer inside the capsule.
+_UNVERSIONED_CAPSULE_DESTRUCTOR_C = ctypes.CFUNCTYPE(None, ctypes.c_void_p)(
+    _unversioned_capsule_destructor
+)
+
+
+@ctypes.CFUNCTYPE(None, ctypes.POINTER(DLManagedTensorVersioned))
+def _versioned_wrapper_deleter(versioned_ptr):
+    """Forward to the legacy deleter, then free the wrapper allocation."""
+    if not versioned_ptr:
+        return
+
+    versioned = versioned_ptr.contents
+    original_ptr = ctypes.cast(versioned.manager_ctx, ctypes.POINTER(DLManagedTensor))
+
+    if original_ptr and original_ptr.contents.deleter:
+        original_ptr.contents.deleter(original_ptr)
+
+    PYTHON_API.PyMem_RawFree(ctypes.cast(versioned_ptr, ctypes.c_void_p))
+
+
+@ctypes.CFUNCTYPE(None, ctypes.POINTER(DLManagedTensor))
+def _unversioned_wrapper_deleter(unversioned_ptr):
+    """Forward to the versioned deleter, then free the wrapper allocation."""
+    if not unversioned_ptr:
+        return
+
+    unversioned = unversioned_ptr.contents
+    original_ptr = ctypes.cast(
+        unversioned.manager_ctx, ctypes.POINTER(DLManagedTensorVersioned)
+    )
+
+    if original_ptr and original_ptr.contents.deleter:
+        original_ptr.contents.deleter(original_ptr)
+
+    PYTHON_API.PyMem_RawFree(ctypes.cast(unversioned_ptr, ctypes.c_void_p))
+
+
+def _wrap_unversioned_as_versioned(unversioned_ptr):
+    """Wrap a legacy DLManagedTensor pointer in a versioned allocation."""
+    versioned_size = ctypes.sizeof(DLManagedTensorVersioned)
+    versioned_mem = PYTHON_API.PyMem_RawMalloc(versioned_size)
+    if not versioned_mem:
+        raise MemoryError("failed to allocate DLManagedTensorVersioned")
+
+    try:
+        versioned_ptr = ctypes.cast(
+            versioned_mem, ctypes.POINTER(DLManagedTensorVersioned)
+        )
+        versioned = versioned_ptr.contents
+
+        versioned.version = DLPackVersion()
+        versioned.version.major = 1
+        versioned.version.minor = 0
+        versioned.manager_ctx = ctypes.cast(unversioned_ptr, ctypes.c_void_p)
+        versioned.deleter = _versioned_wrapper_deleter
+        versioned.flags = 0
+
+        # DLManagedTensor starts with a DLTensor, so copying from the struct base
+        # address into versioned.dl_tensor preserves the payload layout.
+        ctypes.memmove(
+            ctypes.addressof(versioned.dl_tensor),
+            unversioned_ptr,
+            ctypes.sizeof(DLTensor),
+        )
+
+        return versioned_ptr
+    except BaseException:
+        PYTHON_API.PyMem_RawFree(versioned_mem)
+        raise
+
+
+def _wrap_versioned_as_unversioned(versioned_ptr):
+    """Wrap a ``DLManagedTensorVersioned`` pointer in a legacy allocation.
+
+    This is used to expose a versioned tensor to importers that only support the
+    unversioned DLPack protocol (``max_version`` is ``None`` or has a major
+    version of ``0``).
+    """
+    unversioned_size = ctypes.sizeof(DLManagedTensor)
+    unversioned_mem = PYTHON_API.PyMem_RawMalloc(unversioned_size)
+    if not unversioned_mem:
+        raise MemoryError("failed to allocate DLManagedTensor")
+
+    try:
+        unversioned_ptr = ctypes.cast(unversioned_mem, ctypes.POINTER(DLManagedTensor))
+        unversioned = unversioned_ptr.contents
+
+        unversioned.manager_ctx = ctypes.cast(versioned_ptr, ctypes.c_void_p)
+        unversioned.deleter = _unversioned_wrapper_deleter
+
+        # Both structs embed a ``DLTensor`` with identical layout; copy the
+        # payload from the versioned struct into the legacy one.
+        ctypes.memmove(
+            ctypes.addressof(unversioned.dl_tensor),
+            ctypes.addressof(versioned_ptr.contents.dl_tensor),
+            ctypes.sizeof(DLTensor),
+        )
+
+        return unversioned_ptr
+    except BaseException:
+        PYTHON_API.PyMem_RawFree(unversioned_mem)
+        raise
+
+
+def _make_dlpack_versioned_capsule(dl_managed_versioned_ptr):
+    ptr_value = ctypes.cast(dl_managed_versioned_ptr, ctypes.c_void_p).value
+    if not ptr_value:
+        raise ValueError("DLManagedTensorVersioned pointer is null")
+
+    destructor = ctypes.cast(_VERSIONED_CAPSULE_DESTRUCTOR_C, ctypes.c_void_p)
+    return PYTHON_API.PyCapsule_New(ptr_value, DLPACK_VERSIONED_NAME, destructor)
+
+
+def _make_dlpack_capsule(dl_managed_ptr):
+    ptr_value = ctypes.cast(dl_managed_ptr, ctypes.c_void_p).value
+    if not ptr_value:
+        raise ValueError("DLManagedTensor pointer is null")
+
+    destructor = ctypes.cast(_UNVERSIONED_CAPSULE_DESTRUCTOR_C, ctypes.c_void_p)
+    return PYTHON_API.PyCapsule_New(ptr_value, DLPACK_NAME, destructor)
+
+
+def _call_dlpack_with_fallbacks(array, stream, max_version, dl_device, copy):
+    """Try multiple __dlpack__ signatures for broad compatibility.
+
+    This tries both the ``2023.12`` array API signature (with ``max_version``,
+    ``dl_device``, and ``copy`` kwargs), as well as the legacy signature (with only
+    ``stream``). The first signature that does not raise a ``TypeError`` (due to unknown
+    keyword arguments) is used, and the resulting capsule is returned.
+    """
+    last_error = None
+
+    try:
+        return array.__dlpack__(
+            stream=stream,
+            max_version=max_version,
+            dl_device=dl_device,
+            copy=copy,
+        )
+    except TypeError as error:
+        last_error = error
+
+    try:
+        return array.__dlpack__(stream=stream)
+    except TypeError as error:
+        last_error = error
+
+    try:
+        return array.__dlpack__()
+    except TypeError as error:
+        last_error = error
+
+    raise RuntimeError("__dlpack__ call failed") from last_error
+
+
+class DLPackArray:
+    """
+    Take a ctypes pointer to a ``DLManagedTensorVersioned`` and wrap it in a Python
+    object that implements the ``__dlpack__`` protocol. This allows the pointer to be
+    passed to other libraries that support DLPack, while ensuring that the pointer is
+    only used once and that the underlying memory is freed when the object is garbage
+    collected.
+
+    >>> import numpy as np
+    >>> import torch
+    >>> # Get the pointer in some way
+    >>> pointer = ...
+    >>> array = DLPackArray(pointer)
+    >>> # the array can be used with `from_dlpack`
+    >>> use_numpy = True
+    >>> if use_numpy:
+    ...     np_array = np.from_dlpack(array)
+    ...     print(np_array.shape)
+    ... else:
+    ...     torch_tensor = torch.from_dlpack(array)
+    ...     print(torch_tensor.shape)
+    """
+
+    def __init__(self, pointer: ctypes.POINTER(DLManagedTensorVersioned)):
+        """
+        :param pointer: pointer to a ``DLManagedTensorVersioned`` to be re-exposed as
+            Python object following the ``__dlpack__`` protocol.
+        """
+        if not isinstance(pointer, ctypes.POINTER(DLManagedTensorVersioned)):
+            raise TypeError(
+                "`pointer` must be a ctypes.POINTER(DLManagedTensorVersioned), "
+                f"got {type(pointer).__name__}"
+            )
+
+        if not pointer:
+            raise ValueError("`pointer` is null")
+
+        self._pointer = pointer
+
+    def __del__(self):
+        pointer = getattr(self, "_pointer", None)
+        if pointer is None:
+            return
+
+        self._pointer = None
+        if pointer.contents.deleter:
+            pointer.contents.deleter(pointer)
+
+    def __dlpack__(
+        self,
+        stream: int | None = None,
+        max_version: tuple[int, int] | None = None,
+        dl_device: tuple[int, int] | None = None,
+        copy: bool | None = None,
+    ):
+        pointer = self._pointer
+        if pointer is None:
+            raise RuntimeError("can not call __dlpack__ twice on DLPackArray")
+
+        if stream is not None:
+            raise RuntimeError("only `stream=None` is currently supported")
+
+        if dl_device is not None and dl_device != self.__dlpack_device__():
+            raise BufferError("device conversion is not supported")
+
+        if copy is None:
+            copy = False
+
+        if copy:
+            raise BufferError("only `copy=False` is supported")
+
+        if max_version is None or max_version[0] == 0:
+            # The caller only supports the unversioned DLPack protocol (or did
+            # not request a specific version): wrap our versioned tensor into a
+            # legacy ``DLManagedTensor`` capsule.
+            unversioned_ptr = _wrap_versioned_as_unversioned(pointer)
+            result = _make_dlpack_capsule(unversioned_ptr)
+        else:
+            result = _make_dlpack_versioned_capsule(pointer)
+
+        self._pointer = None
+        return result
+
+    def __dlpack_device__(self):
+        if self._pointer is None:
+            raise RuntimeError("can not query __dlpack_device__ after __dlpack__")
+
+        device = self._pointer[0].dl_tensor.device
+        return (device.device_type.value, device.device_id)
+
+    def __repr__(self):
+        if self._pointer is None:
+            return "<DLPackArray (consumed)>"
+
+        return "<DLPackArray>"
+
+
+def array_as_dlpack(
+    array,
+    *,
+    stream=None,
+    max_version: DLPackVersion | tuple[int, int] | None = None,
+    dl_device: DLDevice | tuple[int, int] | None = None,
+    copy: bool | None = None,
+) -> ctypes.POINTER(DLManagedTensorVersioned):
+    """
+    Get a ctypes pointer to a ``DLManagedTensorVersioned`` struct from any array
+    implementing the ``__dlpack__`` protocol. See
+    https://data-apis.org/array-api/latest/API_specification/generated/array_api.array.__dlpack__.html
+    for the protocol specification.
+
+    This function will try to work with older version of the ``__dlpack__`` protocol,
+    wrapping the unversioned ``DLManagedTensor`` returned into a
+    ``DLManagedTensorVersioned``. Some arguments might be ignored in this case, since
+    they do not have an equivalent.
+
+    :param array: any array type that implements the ``__dlpack__`` protocol
+    :param stream: the CUDA or ROCm synchronization stream, passed as-is to the
+        ``__dlpack__`` method of ``array``.
+    :param max_version: the maximum DLPack version that the caller of this function
+        supports. If this is a ``DLPackVersion``, it is converted to the 2-tuple
+        expected by ``__dlpack__``.
+    :param dl_device: the DLPack device type. Default is ``None``, meaning the exported
+        pointer should be on the same device as ``array``. If this is a ``DLDevice``, it
+        is converted to the 2-tuple expected by ``__dlpack__``.
+    :param copy: boolean indicating whether or not to copy the input.
+    """
+
+    if max_version is None:
+        max_version_tuple = None
+    elif isinstance(max_version, DLPackVersion):
+        max_version_tuple = (max_version.major, max_version.minor)
+    elif (
+        isinstance(max_version, tuple)
+        and len(max_version) == 2
+        and isinstance(max_version[0], int)
+        and isinstance(max_version[1], int)
+    ):
+        max_version_tuple = max_version
+    else:
+        raise TypeError(
+            "`max_version` must be a DLPackVersion, a 2-tuple of ints, or None; "
+            f"got {type(max_version).__name__}"
+        )
+
+    if dl_device is None:
+        dl_device_tuple = None
+    elif isinstance(dl_device, DLDevice):
+        dl_device_tuple = (int(dl_device.device_type.value), dl_device.device_id)
+    elif (
+        isinstance(dl_device, tuple)
+        and len(dl_device) == 2
+        and isinstance(dl_device[0], int)
+        and isinstance(dl_device[1], int)
+    ):
+        dl_device_tuple = dl_device
+    else:
+        raise TypeError(
+            "`dl_device` must be a DLDevice, a 2-tuple of ints, or None; "
+            f"got {type(dl_device).__name__}"
+        )
+
+    capsule = _call_dlpack_with_fallbacks(
+        array,
+        stream,
+        max_version_tuple,
+        dl_device_tuple,
+        copy,
+    )
+    capsule_name = PYTHON_API.PyCapsule_GetName(capsule)
+
+    if capsule_name == DLPACK_VERSIONED_NAME:
+        pointer = PYTHON_API.PyCapsule_GetPointer(capsule, DLPACK_VERSIONED_NAME)
+        if not pointer:
+            err = _fetch_pyerr()
+            raise RuntimeError("failed to get pointer from versioned capsule") from err
+
+        result = ctypes.cast(pointer, ctypes.POINTER(DLManagedTensorVersioned))
+
+        status = PYTHON_API.PyCapsule_SetName(capsule, USED_DLPACK_VERSIONED_NAME)
+        if status != 0:
+            err = _fetch_pyerr()
+            raise RuntimeError("failed to mark versioned capsule as used") from err
+
+    elif capsule_name == DLPACK_NAME:
+        pointer = PYTHON_API.PyCapsule_GetPointer(capsule, DLPACK_NAME)
+        if not pointer:
+            err = _fetch_pyerr()
+            raise RuntimeError("failed to get pointer from legacy capsule") from err
+
+        unversioned_ptr = ctypes.cast(pointer, ctypes.POINTER(DLManagedTensor))
+        result = _wrap_unversioned_as_versioned(unversioned_ptr)
+
+        # Only disown the capsule once ``result`` is fully built; if SetName ran
+        # earlier and any subsequent step raised, the capsule destructor would
+        # see the ``used_`` name and skip the deleter, leaking the source tensor.
+        status = PYTHON_API.PyCapsule_SetName(capsule, USED_DLPACK_NAME)
+        if status != 0:
+            err = _fetch_pyerr()
+            raise RuntimeError("failed to mark legacy capsule as used") from err
+    else:
+        # Unexpected capsule name. If ``GetName`` itself failed (returned NULL)
+        # it set a C-API exception which we clear here; otherwise there is
+        # nothing to clear.
+        PYTHON_API.PyErr_Clear()
+        name = capsule_name.decode() if capsule_name else "NULL"
+        raise RuntimeError(
+            f"unexpected capsule name: {name}; expected 'dltensor' "
+            "or 'dltensor_versioned'"
+        )
+
+    actual_device = result.contents.dl_tensor.device
+    actual_device = (actual_device.device_type.value, actual_device.device_id)
+    if dl_device_tuple is not None and actual_device != dl_device_tuple:
+        if result.contents.deleter:
+            result.contents.deleter(result)
+
+        raise ValueError(
+            "DLPack device mismatch: "
+            f"expected type={dl_device_tuple[0]} id={dl_device_tuple[1]}, "
+            f"got type={actual_device[0]} id={actual_device[1]}"
+        )
+
+    return result

ctypes_dlpack-0.1.0.dist-info/METADATA

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: ctypes-dlpack
+Version: 0.1.0
+Summary: Ctypes helpers for DLPack interop
+Author-email: Guillaume Fraux <guillaume.fraux@epfl.ch>
+License-Expression: BSD-3-Clause
+Project-URL: repository, https://github.com/metatensor/ctypes-dlpack
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# ctypes-dlpack
+
+<h4 align="center">
+
+[![tests status](https://github.com/metatensor/ctypes-dlpack/actions/workflows/tests.yml/badge.svg)](https://github.com/metatensor/ctypes-dlpack/actions?query=branch%3Amain)
+[![documentation](https://img.shields.io/badge/📚_documentation-latest-sucess)](https://docs.metatensor.org/ctypes-dlpack/)
+</h4>
+
+The [DLPack](https://dmlc.github.io/dlpack/latest/) standard allows to share
+arrays/tensors data between different frameworks. It is defined as a C API, and
+the standard way to use it from Python is the `__dlpack__` protocol defined in
+the [array
+api](https://data-apis.org/array-api/latest/API_specification/generated/array_api.array.__dlpack__.html),
+which relies on `PyCapsule` to pass the pointer around through Python code.
+
+However, there might be times where one does not have a `PyCapsule` but just a
+raw pointer to the DLPack C struct. In particular, this might be the case when
+adding bindings to a C library through `ctypes` instead of going through a
+CPython extension module. This library is here to bridge this gap, creating
+ctypes pointers from the `__dlpack__` protocol, and making existing pointers
+compatible with this protocol.
+
+This library exposes both the C structs/enums/constants from the DLPack C header
+as `ctypes` types (containing among other the version of the DLPack library
+that was used to generate the ctypes declarations), and a Python API to convert
+between DLPack pointers and Python objects. See the [documentation](http://docs.metatensor.org/ctypes-dlpack/) for more details.
+
+You can install the code with `pip install ctypes-dlpack`.
+
+### License and contributions
+
+This project is distributed under the terms of the [BSD license](LICENSE), and
+[maintained](https://github.com/lab-cosmo/.github/blob/main/Maintainers.md) by
+[@Luthaf](https://github.com/Luthaf), who will reply to issues and pull requests
+opened on this repository as soon as possible. You can mention them directly if
+you did not receive an answer after a couple of days.

ctypes_dlpack-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+ctypes_dlpack/__init__.py,sha256=uUb2KN_4d8_g9XT5nym8HCS4DSLahYVrW6g746WUjdw,1495
+ctypes_dlpack/_c_api.py,sha256=R41osT7m9iwo8bBC-gC6nMexQrGdbhMiX7V_XvrbAr4,4944
+ctypes_dlpack/_dlpack.py,sha256=_dRFVagWaDtBvQ033sPkuJVmKOqdb-K-x8Jo1deoWR0,19207
+ctypes_dlpack-0.1.0.dist-info/licenses/LICENSE,sha256=ePI5b-CYfiIBh1k1S-Mx-pl8PoryJ1cbUq1E94keQgs,1518
+ctypes_dlpack-0.1.0.dist-info/METADATA,sha256=pjXQeW54mtmNdFXENCYhw9YcXi0TEzOOLjxE8HzaXzM,2746
+ctypes_dlpack-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+ctypes_dlpack-0.1.0.dist-info/top_level.txt,sha256=wjlIXBuJ4vMD4BrUkXvvqTsOunDr-8EB9rDiTzPaPwU,14
+ctypes_dlpack-0.1.0.dist-info/RECORD,,

ctypes_dlpack-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ctypes_dlpack-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026 Guillaume Fraux and contributors
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

ctypes_dlpack-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ctypes_dlpack