Add DLPackArray and array_as_dlpack

Author: Luthaf

docs/src/reference.rst docs/src/c-api.rstdocs/src/reference.rst renamed to docs/src/c-api.rst

@@ -1,5 +1,11 @@
-Python API reference
-====================
+
+.. DO NOT EDIT DIRECTLY, automatically generated by ./scripts/update-declarations.py.
+
+DLPack types
+============
+
+The following elements from the C header ``dlpack.h`` are available as
+``ctypes`` types for Python users.
 
 Macros
 ------

docs/src/index.rst

@@ -1,10 +1,30 @@
 ctypes-dlpack
-==============
+=============
 
-Helpers for DLPack interop based on ``ctypes``.
+The `DLPack`_ 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 <py-dlpack>`_, 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.
+
+You can install the code with ``pip install ctypes-dlpack``.
+
+.. _DLPack: https://dmlc.github.io/dlpack/latest/
+.. _py-dlpack: https://data-apis.org/array-api/latest/API_specification/generated/array_api.array.__dlpack__.html
 
 .. toctree::
    :maxdepth: 2
-   :caption: Reference
 
-   reference
+   c-api
+   python-api

docs/src/python-api.rst

@@ -0,0 +1,8 @@
+Python API reference
+====================
+
+
+.. autoclass:: ctypes_dlpack::DLPackArray
+    :members:
+
+.. autofunction:: ctypes_dlpack::array_as_dlpack

scripts/update-declarations.py

@@ -18,7 +18,7 @@
     "https://raw.githubusercontent.com/dmlc/dlpack/{version}/include/dlpack/dlpack.h"
 )
 OUTPUT_PATH = ROOT / "src" / "ctypes_dlpack" / "_c_api.py"
-REFERENCE_PATH = ROOT / "docs" / "src" / "reference.rst"
+REFERENCE_PATH = ROOT / "docs" / "src" / "c-api.rst"
 
 
 GENERATOR = c_generator.CGenerator()
@@ -332,8 +332,16 @@ def generate_python_module(
 def generate_reference_rst(
     defines: dict[str, str], parsed: HeaderVisitor, file: TextIO
 ) -> None:
-    file.write("Python API reference\n")
-    file.write("====================\n\n")
+    file.write("""
+.. DO NOT EDIT DIRECTLY, automatically generated by ./scripts/update-declarations.py.
+
+DLPack types
+============
+
+The following elements from the C header ``dlpack.h`` are available as
+``ctypes`` types for Python users.
+
+""")
 
     file.write("Macros\n")
     file.write("------\n\n")

src/ctypes_dlpack/__init__.py

@@ -1,4 +1,5 @@
 from . import _c_api
+from ._dlpack import DLPackArray, array_as_dlpack
 
 
 __version__ = "0.1.0"
@@ -16,4 +17,11 @@
         value.__module__ = __name__
 
 
+__all__ = [
+    *_public_members.keys(),
+    "DLPackArray",
+    "array_as_dlpack",
+]
+
+
 del _public_members

src/ctypes_dlpack/_c_api.py

@@ -6,8 +6,6 @@
 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:
@@ -42,7 +40,6 @@ def __eq__(self, other):
 
         return type(self) is type(other) and self.value == other.value
 
-
 class DLDeviceType(_Enum):
     pass
     kDLCPU = 1