Replace Cython with nanobind for Python bindings (#272)

The Cython-based bindings required extensive marshaling between Python
and C++ data structures, causing performance overhead and maintenance
complexity. Each call crossed the language boundary multiple times,
converting maps, thread lists, and frame data back and forth.

This migration moves to nanobind with scikit-build-core for the build
system. The key architectural change is moving logic that previously
lived in Cython or Python into C++: maps parsing, version detection,
and thread construction now happen entirely in C++ before returning
results to Python. This eliminates round-trips and simplifies the
codebase by removing the Cython layer entirely. The Python API remains
unchanged.

Signed-off-by: Pablo Galindo Salgado <pablogsal@gmail.com>

Author: pablogsal

.github/workflows/build_wheels.yml

@@ -68,7 +68,7 @@ jobs:
       - name: Build wheels
         uses: pypa/cibuildwheel@v3.4.0
         env:
-          CIBW_BUILD: "cp3{8..14}{t,}-${{ matrix.wheel_type }}"
+          CIBW_BUILD: "cp3{9..14}{t,}-${{ matrix.wheel_type }}"
           CIBW_ARCHS_LINUX: auto
           CIBW_ENABLE: cpython-prerelease cpython-freethreading
       - uses: actions/upload-artifact@v7
@@ -157,7 +157,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python_version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13", "3.13t", "3.14", "3.14t"]
+        python_version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.13t", "3.14", "3.14t"]
     steps:
       - uses: actions/checkout@v6
       - name: Set up Python
@@ -192,7 +192,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python_version: ["3.8", "3.13", "3.14"]
+        python_version: ["3.9", "3.13", "3.14"]
     steps:
       - uses: actions/checkout@v6
       - name: Set up Python

.github/workflows/coverage.yml

@@ -38,29 +38,40 @@ jobs:
           sudo apt-get install -qy \
             gdb \
             lcov \
+            cmake \
+            ninja-build \
             libdw-dev \
             libelf-dev \
             python3.10-dev \
             python3.10-dbg
       - name: Install Python dependencies
         run: |
-          python3 -m pip install --upgrade pip cython pkgconfig
-          make test-install
+          python3 -m pip install --upgrade pip scikit-build-core nanobind
+          python3 -m pip install -e . -r requirements-test.txt
       - name: Disable ptrace security restrictions
         run: |
           echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope
-      - name: Compute Python + Cython coverage
+      - name: Compute Python coverage
         run: |
-          make pycoverage
+          python3 -m pytest -vvv --log-cli-level=info -s --color=yes \
+                      --cov=pystack --cov=tests --cov-config=pyproject.toml --cov-report=term \
+                      --cov-append tests --cov-fail-under=85
+          python3 -m coverage lcov -i -o pycoverage.lcov
+          genhtml *coverage.lcov --branch-coverage --output-directory pystack-coverage
       - name: Compute C++ coverage
         run: |
-          make ccoverage
-      - name: Upload {P,C}ython report to Codecov
+          rm -rf build
+          CFLAGS="-O0 -pg --coverage" CXXFLAGS="-O0 -pg --coverage" SKBUILD_BUILD_DIR=build pip install -e . --no-build-isolation
+          python3 -m pytest tests -v
+          find build -name "*.gcda" -o -name "*.gcno" | head -5
+          lcov --capture --directory build --output-file cppcoverage.lcov
+          lcov --extract cppcoverage.lcov '*/src/pystack/_pystack/*' --output-file cppcoverage.lcov
+      - name: Upload Python report to Codecov
         uses: codecov/codecov-action@v5
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           files: pycoverage.lcov
-          flags: python_and_cython
+          flags: python
       - name: Upload C++ report to Codecov
         uses: codecov/codecov-action@v5
         with:

.github/workflows/lint_and_docs.yml

@@ -22,7 +22,7 @@ jobs:
           python3 -m pip install -e .
       - name: Lint sources
         run: |
-          make lint
+          make lint PYTHON=python3
           python3 -m pre_commit run --all-files --hook-stage pre-push
       - name: Build docs
         run: |

CMakeLists.txt

@@ -0,0 +1,24 @@
+cmake_minimum_required(VERSION 3.17...3.27)
+
+project(pystack LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+
+# Find Python
+find_package(Python 3.9 COMPONENTS Interpreter Development.Module REQUIRED)
+
+# Find nanobind
+execute_process(
+    COMMAND "${Python_EXECUTABLE}" -m nanobind --cmake_dir
+    OUTPUT_STRIP_TRAILING_WHITESPACE OUTPUT_VARIABLE nanobind_ROOT)
+find_package(nanobind CONFIG REQUIRED)
+
+# Find libelf and libdw via pkg-config
+find_package(PkgConfig REQUIRED)
+pkg_check_modules(LIBELF REQUIRED libelf)
+pkg_check_modules(LIBDW REQUIRED libdw)
+
+# Add the extension module subdirectory
+add_subdirectory(src/pystack/_pystack)

Makefile

@@ -1,4 +1,4 @@
-PYTHON ?= python
+PYTHON ?= python3
 DOCKER_IMAGE ?= pystack
 DOCKER_SRC_DIR ?= /src
 
@@ -13,19 +13,19 @@ ENV :=
 
 .PHONY: build
 build:  ## (default) Build package extensions in-place
-	$(PYTHON) setup.py build_ext --inplace
+	$(ENV) $(PIP_INSTALL) -e .
 
 .PHONY: dist
 dist:  ## Generate Python distribution files
-	$(PYTHON) -m pep517.build .
+	$(PYTHON) -m build
 
 .PHONY: install-sdist
 install-sdist: dist  ## Install from source distribution
 	$(ENV) $(PIP_INSTALL) $(wildcard dist/*.tar.gz)
 
 .PHONY: test-install
 test-install:  ## Install with test dependencies
-	$(ENV) CYTHON_TEST_MACROS=1 $(PIP_INSTALL) -e . -r requirements-test.txt
+	$(ENV) $(PIP_INSTALL) -e . -r requirements-test.txt
 
 .PHONY: docker-build
 docker-build:  ## Build the Docker image
@@ -59,7 +59,7 @@ check:  ## Run the test suite
 pycoverage:  ## Run the test suite, with Python code coverage
 	$(PYTHON) -m pytest -vvv --log-cli-level=info -s --color=yes \
 				--cov=pystack --cov=tests --cov-config=pyproject.toml --cov-report=term \
-				--cov-append $(PYTEST_ARGS) tests --cov-fail-under=92
+				--cov-append $(PYTEST_ARGS) tests --cov-fail-under=85
 	$(PYTHON) -m coverage lcov -i -o pycoverage.lcov
 	genhtml *coverage.lcov --branch-coverage --output-directory pystack-coverage
 
@@ -71,10 +71,9 @@ valgrind:  ## Run valgrind, with the correct configuration
 .PHONY: ccoverage
 ccoverage:  ## Run the test suite, with C++ code coverage
 	$(MAKE) clean
-	CFLAGS="$(CFLAGS) -O0 -pg --coverage" CXXFLAGS="$(CXXFLAGS) -O0 -pg --coverage" $(MAKE) build
+	CFLAGS="-O0 -pg --coverage" CXXFLAGS="-O0 -pg --coverage" $(PIP_INSTALL) -e .
 	$(MAKE) check
-	gcov -i build/*/src/pystack/_pystack -i -d
-	lcov --capture --directory .  --output-file cppcoverage.lcov
+	lcov --capture --directory . --output-file cppcoverage.lcov
 	lcov --extract cppcoverage.lcov '*/src/pystack/_pystack/*' --output-file cppcoverage.lcov
 	genhtml *coverage.lcov --branch-coverage --output-directory pystack-coverage
 
@@ -116,6 +115,7 @@ clean:  ## Clean any built/generated artifacts
 	find . | grep -E '(\.o|\.gcda|\.gcno|\.gcov\.json\.gz)' | xargs rm -rf
 	find . | grep -E '(__pycache__|\.pyc|\.pyo)' | xargs rm -rf
 	rm -rf build
+	rm -rf _skbuild
 	rm -f src/pystack/_pystack.*.so
 	rm -f {cpp,py}coverage.lcov
 	rm -rf pystack-coverage

news/272.feature.rst

@@ -0,0 +1,2 @@
+Replace Cython with nanobind for Python bindings, improving performance by
+eliminating round-trips between Python and C++.

pyproject.toml

@@ -1,13 +1,57 @@
 [build-system]
+requires = ["scikit-build-core>=0.4", "nanobind>=1.8"]
+build-backend = "scikit_build_core.build"
 
-requires = [
-     "setuptools",
-     "wheel",
-     "Cython",
-     "pkgconfig"
+[project]
+name = "pystack"
+dynamic = ["version"]
+description = "Analysis of the stack of remote python processes"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "Apache-2.0"}
+authors = [
+    {name = "Pablo Galindo Salgado"}
 ]
+classifiers = [
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Topic :: Software Development :: Debuggers",
+]
+
+[project.urls]
+Homepage = "https://github.com/bloomberg/pystack"
+
+[project.scripts]
+pystack = "pystack.__main__:main"
 
-build-backend = 'setuptools.build_meta'
+[tool.scikit-build]
+wheel.packages = ["src/pystack"]
+wheel.install-dir = "pystack"
+wheel.exclude = ["pystack/_pystack/**"]
+metadata.version.provider = "scikit_build_core.metadata.regex"
+metadata.version.input = "src/pystack/_version.py"
+sdist.include = ["src/pystack/_version.py"]
+sdist.exclude = [
+  ".devcontainer/**",
+  ".github/**",
+  ".vscode/**",
+  "CONTRIBUTING.md",
+  "Dockerfile",
+  "docs/**",
+  "tests/**",
+  "uv.lock",
+]
+
+[tool.scikit-build.cmake.define]
+CMAKE_BUILD_TYPE = "Release"
 
 [tool.ruff]
 line-length = 95
@@ -43,15 +87,15 @@ type = [
 underlines = "-~"
 
 [tool.cibuildwheel]
-build = ["cp38-*", "cp39-*", "cp310-*", "cp311-*"]
+build = ["cp39-*", "cp310-*", "cp311-*", "cp312-*", "cp313-*", "cp314-*"]
 manylinux-x86_64-image = "manylinux2014"
 manylinux-i686-image = "manylinux2014"
 musllinux-x86_64-image = "musllinux_1_2"
 skip = "*-musllinux_aarch64"
 
 [tool.cibuildwheel.linux]
 before-all = [
-  "yum install -y libzstd-devel",
+  "yum install -y libzstd-devel cmake",
   "cd /",
   "VERS=0.193",
   "curl https://sourceware.org/elfutils/ftp/$VERS/elfutils-$VERS.tar.bz2 > ./elfutils.tar.bz2",
@@ -74,7 +118,7 @@ before-all = [
   # set the FNM_EXTMATCH macro to get the build to succeed is seen here:
   # https://git.alpinelinux.org/aports/tree/main/elfutils/musl-macros.patch
   "cd /",
-  "apk add --update argp-standalone bison bsd-compat-headers bzip2-dev flex-dev libtool linux-headers musl-fts-dev musl-libintl musl-obstack-dev xz-dev zlib-dev zstd-dev",
+  "apk add --update argp-standalone bison bsd-compat-headers bzip2-dev flex-dev libtool linux-headers musl-fts-dev musl-libintl musl-obstack-dev xz-dev zlib-dev zstd-dev cmake",
   "VERS=0.193",
   "curl https://sourceware.org/elfutils/ftp/$VERS/elfutils-$VERS.tar.bz2 > ./elfutils.tar.bz2",
   "tar -xf elfutils.tar.bz2",
@@ -88,16 +132,12 @@ before-all = [
 ]
 
 [tool.coverage.run]
-plugins = [
-  "Cython.Coverage",
-]
 source = [
   "src/pystack",
 ]
 branch = true
 parallel = true
 omit = [
-  "stringsource",
   "tests/integration/*program*.py",
 ]