Add Cython utils needed for zero-copy import and export.

Author: eriknw

LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2021 Anaconda Inc., Graphegon, and contributors
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

MANIFEST.in

@@ -0,0 +1,6 @@
+include setup.py
+include README.md
+include LICENSE
+include suitesparse_graphblas/*.pxd
+include suitesparse_graphblas/*.pyx
+include suitesparse_graphblas/*.h

pyproject.toml

@@ -0,0 +1,5 @@
+[build-system]
+requires = ["setuptools", "wheel", "numpy >= 1.15"]
+
+[tool.black]
+line-length = 100

setup.cfg

@@ -0,0 +1,16 @@
+[aliases]
+test=pytest
+
+[flake8]
+max-line-length = 100
+exclude =
+    versioneer.py,
+    grblas/tests/test_formatting.py,
+ignore =
+    E203,   # whitespace before ':'
+    E231,   # Multiple spaces around ","
+    W503,   # line break before binary operator
+
+[tool:pytest]
+testpaths = suitesparse_graphblas/tests
+

setup.py

@@ -1,14 +1,66 @@
-from setuptools import setup, find_packages
+from setuptools import setup, find_packages, Extension
+from glob import glob
+try:
+    from Cython.Build import cythonize
+    from Cython.Compiler.Options import get_directive_defaults
+
+    use_cython = True
+except ImportError:
+    use_cython = False
+import numpy as np
+import os
+import sys
+
+define_macros = [("NPY_NO_DEPRECATED_API", "NPY_1_7_API_VERSION")]
+
+if use_cython:
+    suffix = ".pyx"
+    directive_defaults = get_directive_defaults()
+    directive_defaults["binding"] = True
+    directive_defaults["language_level"] = 3
+    if os.environ.get("CYTHON_COVERAGE"):
+        directive_defaults["linetrace"] = True
+        define_macros.append(("CYTHON_TRACE_NOGIL", "1"))
+else:
+    suffix = ".c"
+
+include_dirs = [np.get_include(), os.path.join(sys.prefix, "include")]
+ext_modules = [
+    Extension(
+        name[: -len(suffix)].replace("/", ".").replace("\\", "."),
+        [name],
+        include_dirs=include_dirs,
+        define_macros=define_macros,
+    )
+    for name in glob(f"suitesparse_graphblas/**/*{suffix}", recursive=True)
+]
+if use_cython:
+    ext_modules = cythonize(ext_modules, include_path=include_dirs)
+
+with open("README.md") as f:
+    long_description = f.read()
+
+package_data = {"suitesparse_graphblas": ["*.pyx", "*.pxd", "*.h"]}
+if sys.platform == "win32":
+    package_data["suitesparse_graphblas"].append("*.dll")
 
 setup(
     name='suitesparse-graphblas',
     version='4.0.3',
     description='SuiteSparse:GraphBLAS Python bindings.',
+    long_description=long_description,
+    long_description_content_type="text/markdown",
     packages=find_packages(),
     author='Michel Pelletier, James Kitchen, Erik Welch',
+    author_email="[email protected],[email protected]",
+    url="https://github.com/GraphBLAS/python-suitesparse-graphblas",
+    ext_modules=ext_modules,
     cffi_modules=["suitesparse_graphblas/build.py:ffibuilder"],
-    install_requires=["cffi>=1.0.0"],
+    python_requires=">=3.7",
+    install_requires=["cffi>=1.0.0", "numpy>=1.15"],
     setup_requires=["cffi>=1.0.0", "pytest-runner"],
     tests_require=["pytest"],
+    license="Apache License 2.0",
+    package_data=package_data,
+    include_package_data=True,
 )
-

suitesparse_graphblas/tests/__init__.py

@@ -0,0 +1,34 @@
+from numpy cimport ndarray
+from libc.stdint cimport uint64_t
+
+cdef extern from "numpy/arrayobject.h" nogil:
+    # These aren't public (i.e., "extern"), but other projects use them too
+    void *PyDataMem_NEW(size_t)
+    void *PyDataMem_NEW_ZEROED(size_t, size_t)
+    void *PyDataMem_RENEW(void *, size_t)
+    void PyDataMem_FREE(void *)
+    # These are available in newer Cython versions
+    void PyArray_ENABLEFLAGS(ndarray, int flags)
+    void PyArray_CLEARFLAGS(ndarray, int flags)
+
+ctypedef enum GrB_Mode:
+    GrB_NONBLOCKING
+    GrB_BLOCKING
+
+ctypedef uint64_t (*GxB_init)(
+    GrB_Mode,
+    void *(*user_malloc_function)(size_t),
+    void *(*user_calloc_function)(size_t, size_t),
+    void *(*user_realloc_function)(void *, size_t),
+    void (*user_free_function)(void *),
+    bint,  # user_malloc_is_thread_safe
+)
+
+cpdef int call_gxb_init(ffi, lib, int mode)
+
+cpdef ndarray claim_buffer(ffi, cdata, size_t size, dtype)
+
+cpdef ndarray claim_buffer_2d(ffi, cdata, size_t cdata_size, size_t nrows, size_t ncols, dtype, bint is_c_order)
+
+cpdef unclaim_buffer(ndarray array)
+

tests/test_package.py renamed to suitesparse_graphblas/tests/test_package.py

@@ -0,0 +1,70 @@
+import numpy as np
+from numpy cimport (
+    import_array, ndarray, npy_intp,
+    PyArray_SimpleNewFromData, PyArray_New,
+    NPY_ARRAY_OWNDATA, NPY_ARRAY_WRITEABLE, NPY_ARRAY_F_CONTIGUOUS,
+)
+from libc.stdint cimport uintptr_t
+
+import_array()
+
+cpdef int call_gxb_init(ffi, lib, int mode):
+    # We need to call `GxB_init`, but we didn't compile Cython against GraphBLAS.  So, we get it from cffi.
+    # Step 1: ffi.addressof(lib, "GxB_init")
+    #    Return type: cffi.cdata object of a function pointer.  Can't cast to int.
+    # Step 2: ffi.cast("uintptr_t", ...)
+    #    Return type: cffi.cdata object of a uintptr_t type, an unsigned pointer.  Can cast to int.
+    # Step 3: int(...)
+    #    Return type: int.  The physical address of the function.
+    # Step 4: <uintptr_t>(...)
+    #    Return type: uintptr_t in Cython.  Cast Python int to Cython integer for pointers.
+    # Step 5: <GsB_init>(...)
+    #    Return: function pointer in Cython!
+
+    cdef GxB_init func = <GxB_init><uintptr_t>int(ffi.cast("uintptr_t", ffi.addressof(lib, "GxB_init")))
+    return func(<GrB_Mode>mode, PyDataMem_NEW, PyDataMem_NEW_ZEROED, PyDataMem_RENEW, PyDataMem_FREE, True)
+
+
+cpdef ndarray claim_buffer(ffi, cdata, size_t size, dtype):
+    cdef:
+        npy_intp dims = size
+        uintptr_t ptr = int(ffi.cast("uintptr_t", cdata))
+        ndarray array = PyArray_SimpleNewFromData(1, &dims, dtype.num, <void*>ptr)
+    PyArray_ENABLEFLAGS(array, NPY_ARRAY_OWNDATA)
+    return array
+
+
+cpdef ndarray claim_buffer_2d(ffi, cdata, size_t cdata_size, size_t nrows, size_t ncols, dtype, bint is_c_order):
+    cdef:
+        size_t size = nrows * ncols
+        ndarray array
+        uintptr_t ptr
+        npy_intp dims[2]
+    if cdata_size == size:
+        ptr = int(ffi.cast("uintptr_t", cdata))
+        dims[0] = nrows
+        dims[1] = ncols
+        if is_c_order:
+            array = PyArray_SimpleNewFromData(2, dims, dtype.num, <void*>ptr)
+        else:
+            array = PyArray_New(
+                ndarray, 2, dims, dtype.num, NULL, <void*>ptr, -1,
+                NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_WRITEABLE, <object>NULL
+            )
+        PyArray_ENABLEFLAGS(array, NPY_ARRAY_OWNDATA)
+    elif cdata_size > size:  # pragma: no cover
+        array = claim_buffer(ffi, cdata, cdata_size, dtype)
+        if is_c_order:
+            array = array[:size].reshape((nrows, ncols))
+        else:
+            array = array[:size].reshape((ncols, nrows)).T
+    else:  # pragma: no cover
+        raise ValueError(
+            f"Buffer size too small: {cdata_size}.  "
+            f"Unable to create matrix of size {nrows}x{ncols} = {size}"
+        )
+    return array
+
+
+cpdef unclaim_buffer(ndarray array):
+    PyArray_CLEARFLAGS(array, NPY_ARRAY_OWNDATA | NPY_ARRAY_WRITEABLE)