Expose cython API for external use (#234)

* Expose cython API for internal use

* fix typeo

* Expose Cython API for external use

* Add Cython test

* Install cython in tests

* fix syntax for 2.7 and 3.5

* Fix lint check

* Call pytest on directory

* Build cython test in coverage-lint

* Only run cython test if import succeeds

* No bare except

.github/workflows/coverage-lint.yml

@@ -34,7 +34,10 @@ jobs:
         run: pylint --disable=all --enable=import-error tests/
 
       - name: Coverage
-        run: pytest --cov=h3 --full-trace --cov-report=xml
+        run: |
+          pip install Cython
+          cythonize -i tests/cython_example.pyx
+          pytest --cov=h3 --full-trace --cov-report=xml
 
       - name: Upload coverage to Codecov
         uses: codecov/[email protected]

.github/workflows/tests.yml

@@ -47,4 +47,7 @@ jobs:
           pip install .[all]
 
       - name: Tests
-        run: pytest --cov=h3 --full-trace
+        run: |
+          pip install Cython
+          cythonize -i tests/cython_example.pyx
+          pytest tests --cov=h3 --full-trace

.gitignore

@@ -3,6 +3,8 @@ h3c/
 .cache/
 h3/out/
 
+# Generated C code from Cython test
+tests/*.c
 # Cython HTML annotations
 *.html
 

CMakeLists.txt

@@ -19,3 +19,10 @@ add_subdirectory(src/h3lib)
 # Build the rest (other than the core library dependency) as shared
 set(BUILD_SHARED_LIBS ON)
 add_subdirectory(src/h3)
+
+# Include built h3api.h for Cython API
+install(
+    FILES
+        "${CMAKE_CURRENT_BINARY_DIR}/src/h3lib/src/h3lib/include/h3api.h"
+    DESTINATION
+        src/h3/_cy)

makefile

@@ -35,7 +35,8 @@ annotations: rebuild
 	cp _skbuild/*/cmake-build/src/h3/_cy/*.html ./annotations
 
 test:
-	env/bin/pytest tests/* --cov=h3 --cov-report term-missing --durations=10
+	env/bin/cythonize -i tests/cython_example.pyx
+	env/bin/pytest tests --cov=h3 --cov-report term-missing --durations=10
 
 lint:
 	env/bin/flake8 src/h3 setup.py tests

src/h3/_cy/CMakeLists.txt

@@ -23,3 +23,19 @@ add_cython_file(cells)
 add_cython_file(edges)
 add_cython_file(to_multipoly)
 add_cython_file(unstable_vect)
+
+# Include pyx and pxd files in distribution for use by Cython API
+install(
+    FILES
+        cells.pxd
+        cells.pyx
+        edges.pxd
+        edges.pyx
+        geo.pxd
+        geo.pyx
+        h3lib.pxd
+        util.pxd
+        util.pyx
+    DESTINATION
+        src/h3/_cy
+)

tests/cython_example.pyx

@@ -0,0 +1,18 @@
+from cython cimport boundscheck, wraparound
+
+from h3._cy.h3lib cimport H3int
+from h3._cy.geo cimport geo_to_h3
+
+@boundscheck(False)
+@wraparound(False)
+cpdef void geo_to_h3_vect(
+    const double[:] lat,
+    const double[:] lng,
+    int res,
+    H3int[:] out
+):
+
+    cdef Py_ssize_t i
+
+    for i in range(len(lat)):
+        out[i] = geo_to_h3(lat[i], lng[i], res)

tests/test_cython.py

@@ -0,0 +1,28 @@
+import numpy as np
+
+# Avoid checking for import-error here because cython_example may not have
+# been compiled yet.
+try:
+    from .cython_example import geo_to_h3_vect  # pylint: disable=import-error
+except ImportError:
+    geo_to_h3_vect = None
+
+np.random.seed(0)
+
+
+def test_cython_api():
+    if geo_to_h3_vect is None:
+        print("Not running Cython test because cython example was not compiled")
+        return
+
+    N = 100000
+
+    lats, lngs = np.random.uniform(0, 90, N), np.random.uniform(0, 90, N)
+    res = 9
+
+    lats = np.array(lats, dtype=np.float64)
+    lngs = np.array(lngs, dtype=np.float64)
+    out = np.zeros(len(lats), dtype="uint64")
+    geo_to_h3_vect(lats, lngs, res, out)
+
+    assert out[0] == 617284541015654399