Demo: Add a C/Cython API

Author: oscarbenjamin

.github/workflows/buildwheel.yml

@@ -329,6 +329,52 @@ jobs:
       - run: spin run -- pytest --doctest-glob='*.rst' doc/source
       - run: spin docs
 
+  test_cython_c_api:
+    name: 'Test C API with Cython consumers'
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: '3.13'
+      - run: sudo apt-get update
+      - run: sudo apt-get install libflint-dev
+      - run: pip install "cython==3.3.0" meson-python ninja
+      - run: pip wheel --no-build-isolation --no-deps --wheel-dir=/tmp/python-flint-wheel .
+      - run: pip install /tmp/python-flint-wheel/python_flint-*.whl
+      - name: Build examples with Cython 3.1 through 3.3
+        run: |
+          for version in 3.1.0 3.2.9 3.3.0; do
+            pip install "cython==$version"
+            pip install --no-build-isolation --no-deps --force-reinstall ./examples/cython/capi
+            pip install --no-build-isolation --no-deps --force-reinstall ./examples/cython/flint
+            (cd /tmp && python "$GITHUB_WORKSPACE/examples/cython/capi/test_capi.py")
+            (cd /tmp && python "$GITHUB_WORKSPACE/examples/cython/flint/test_flint.py")
+          done
+      - name: Capsule-only example has no FLINT dependency
+        run: |
+          python - <<'PY'
+          import _flint_capi_example
+          import subprocess
+          dependencies = subprocess.check_output(
+              ["ldd", _flint_capi_example.__file__], text=True)
+          print(dependencies)
+          assert "libflint" not in dependencies
+          PY
+      - name: Installed API files are present
+        run: |
+          cd /tmp
+          python - <<'PY'
+          import flint
+          from pathlib import Path
+          package = Path(flint.__file__).parent
+          assert (package / "__init__.pxd").is_file()
+          assert (package / "__init__.cython-31.pxd").is_file()
+          assert (Path(flint.get_include()) / "python_flint" / "fmpz.h").is_file()
+          PY
+
   # Test build with minimum Cython and meson-python versions.
   test_old_build_requires:
     name: 'Test old Cython/meson-python'
@@ -349,7 +395,7 @@ jobs:
       # We don't need to specify ninja as a requirement in pyproject.toml
       # because without --no-build-isolation meson-python handles it
       # automatically in get_requirements_for_build_wheel().
-      - run: 'pip install "cython==3.0.11" "meson-python==0.18" "ninja<1.11"'
+      - run: 'pip install "cython==3.1.0" "meson-python==0.18" "ninja<1.11"'
       - run: pip install --no-build-isolation .
       - run: python -m flint.test --verbose
 

README.md

@@ -150,9 +150,8 @@ Compatible versions:
 | `0.7.0`      | 16th Mar 2025 | `3.11-3.13` | `3.0-3.2`  | `3.0.11-3.1.0a1` |
 | `0.6.0`      |  1st Feb 2024 | `3.9-3.12`  | `3.0` only | `3.0` only       |
 
-The requirement for Cython 3.1 is only for CPython's free-threaded build.
-Otherwise Cython 3.0 is fine. Cython 3.2 is required for a stable ABI build of
-python-flint.
+Cython 3.1 or newer is required. Cython 3.2 is required for a stable ABI build
+of python-flint.
 
 As of python-flint 0.7.0, CPython 3.13 [PEP
 703](https://peps.python.org/pep-0703/) free-threaded (no-GIL) builds of

doc/source/build.rst

@@ -229,7 +229,7 @@ active Python environment before running ``pip install``.
 To build without build isolation with ``python-flint >= 0.7.0`` the 
 dependencies should first be installed in the active Python environment::
 
-    pip install Cython==3.0 meson meson-python ninja
+    pip install Cython==3.1 meson meson-python ninja
     pip install --no-build-isolation .
 
 The ``meson`` build system will detect the versions of ``FLINT`` and Cython

doc/source/c_api.rst

@@ -0,0 +1,49 @@
+Experimental C API
+==================
+
+python-flint provides an experimental version 1 C API for ``fmpz``. The API
+may change between releases and is not yet a long-term ABI stability promise.
+
+Cython consumers
+----------------
+
+Cython 3.1 or newer can use the installed declarations directly::
+
+    from flint cimport fmpz, fmpz_add, fmpz_get_value
+
+``fmpz_add(a, b)`` returns a new ``fmpz`` and operates entirely through the
+python-flint capsule. Extensions using only this operation do not need FLINT
+headers or a direct FLINT link. See ``examples/cython/capi``.
+
+``fmpz_get_value(value)`` returns a read-only, borrowed pointer to FLINT
+storage. It remains valid only while ``value`` is alive. Never clear or mutate
+it, retain it independently of its owner, or use it after the owner is
+released. Direct consumers must compile and link against the same compatible
+FLINT ABI/build as python-flint. In particular, this is not safe with wheels
+containing a private, renamed FLINT. See ``examples/cython/flint``.
+
+C consumers
+-----------
+
+Include the installed header and import the capsule before using it::
+
+    #include <python_flint/fmpz.h>
+
+    if (PyFlint_Import() < 0)
+        return NULL;
+    result = PyFlint_FMPZ_Add(left, right);  /* new reference */
+
+``PyFlint_FMPZ_GetValue`` has the same borrowed, read-only ownership rules as
+the Cython wrapper. Both operations return ``NULL`` with a Python exception set
+on failure, and reject objects that are not ``flint.fmpz`` instances.
+
+Header location
+---------------
+
+Build systems can locate ``python_flint/fmpz.h`` using::
+
+    import flint
+    print(flint.get_include())
+
+The public header and Cython declarations contain no details of python-flint's
+private extension-object layout.

doc/source/index.rst

@@ -29,6 +29,7 @@ Introduction
    :maxdepth: 2
 
    install.rst
+   c_api.rst
    general.rst
    build.rst
    workflow.rst

examples/cython/capi/README.md

@@ -0,0 +1,9 @@
+# Capsule-only Cython example
+
+This extension uses `fmpz_add` through python-flint's capsule API. It neither
+includes FLINT headers nor links to FLINT.
+
+```console
+python -m pip install .
+python test_capi.py
+```

examples/cython/capi/_flint_capi_example.pyx

@@ -0,0 +1,6 @@
+from flint cimport fmpz, fmpz_add
+
+
+def add(fmpz a, fmpz b):
+    """Add through python-flint's capsule; no FLINT linkage is needed."""
+    return fmpz_add(a, b)

examples/cython/capi/meson.build

@@ -0,0 +1,12 @@
+project('python-flint-capi-example', 'cython', 'c', meson_version: '>=1.3')
+py = import('python').find_installation(pure: false)
+flint_include = run_command(
+  py, '-c', 'import flint; print(flint.get_include())', check: true,
+).stdout().strip()
+py.extension_module(
+  '_flint_capi_example', '_flint_capi_example.pyx',
+  include_directories: include_directories(flint_include),
+  install: true,
+)
+test('capsule API example', py, args: files('test_capi.py'),
+     env: {'PYTHONPATH': meson.current_build_dir()})

examples/cython/capi/pyproject.toml

@@ -0,0 +1,8 @@
+[build-system]
+requires = ["meson-python", "cython>=3.1", "python-flint"]
+build-backend = "mesonpy"
+
+[project]
+name = "python-flint-capi-example"
+version = "0.1.0"
+dependencies = ["python-flint"]

examples/cython/capi/test_capi.py

@@ -0,0 +1,12 @@
+from flint import fmpz
+from _flint_capi_example import add
+
+a = fmpz(2) ** 300
+b = fmpz(3) ** 200
+assert add(a, b) == a + b
+try:
+    add(1, b)
+except TypeError:
+    pass
+else:
+    raise AssertionError("wrong argument type did not raise TypeError")