From: Kefu Chai <k.chai@proxmox.com>
Date: Mon, 19 Jan 2026 11:19:56 +0000 (+0800)
Subject: pybind: add pyproject.toml to fix ReadTheDocs builds with pip 25.3+
X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=7dd00caa6b4afb18d6821a01bcb608e7766e3cd7;p=ceph.git

pybind: add pyproject.toml to fix ReadTheDocs builds with pip 25.3+

ReadTheDocs builds started failing when pip 25.3 began enforcing PEP 517
build isolation. Under build isolation, pip creates a clean temporary
environment to build packages. Without pyproject.toml declaring build
dependencies, Cython is not available in this isolated environment,
causing builds to fail.

Error from failing builds:
  Processing ./src/pybind/rados
    Getting requirements to build wheel: finished with status 'error'
    × Getting requirements to build wheel did not run successfully.
    │ exit code: 1
    ╰─> [2 lines of output]
        ERROR: Cannot find Cythonized file rados.c
        WARNING: Cython is not installed.

pip 25.3 removed the --no-use-pep517 option and no longer calls
setup.py bdist_wheel, enforcing PEP 517 build isolation by default.
Without pyproject.toml, pip cannot install Cython in the isolated
build environment, preventing the generation of .c files from .pyx
sources during the build.

This commit adds pyproject.toml to all four pybind modules (rados,
cephfs, rbd, rgw) declaring Cython>=0.29 as a build dependency. This
ensures Cython is available in pip 25.3's isolated build environment,
allowing the build to proceed successfully.

How it works:
  ReadTheDocs builds pybind modules by running:
    pip install -r admin/doc-pybind.txt

  This file lists local directory paths:
    src/pybind/rados
    src/pybind/cephfs
    src/pybind/rbd
    src/pybind/rgw

  When pip processes each local directory, it automatically:
  1. Looks for pyproject.toml in that directory (per PEP 517/518)
  2. Reads the [build-system] section
  3. Installs the dependencies listed in "requires" into an isolated
     build environment
  4. Invokes the build backend (setup.py via setuptools.build_meta)

  With pyproject.toml present, Cython is now installed in step 3,
  making it available when setup.py runs in step 4.

References:
- pip 25.3 Changelog: https://pip.pypa.io/en/stable/news/
- pip Issue: https://github.com/pypa/pip/issues/6334
- PEP 517 (Build System Interface): https://peps.python.org/pep-0517/
- PEP 518 (Build System Requirements): https://peps.python.org/pep-0518/

Signed-off-by: Kefu Chai <k.chai@proxmox.com>
---

diff --git a/src/pybind/cephfs/pyproject.toml b/src/pybind/cephfs/pyproject.toml
new file mode 100644
index 000000000000..2bf5ec8096be
--- /dev/null
+++ b/src/pybind/cephfs/pyproject.toml
@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools", "wheel", "Cython"]
+build-backend = "setuptools.build_meta"
diff --git a/src/pybind/rados/pyproject.toml b/src/pybind/rados/pyproject.toml
new file mode 100644
index 000000000000..2bf5ec8096be
--- /dev/null
+++ b/src/pybind/rados/pyproject.toml
@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools", "wheel", "Cython"]
+build-backend = "setuptools.build_meta"
diff --git a/src/pybind/rbd/pyproject.toml b/src/pybind/rbd/pyproject.toml
new file mode 100644
index 000000000000..2bf5ec8096be
--- /dev/null
+++ b/src/pybind/rbd/pyproject.toml
@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools", "wheel", "Cython"]
+build-backend = "setuptools.build_meta"
diff --git a/src/pybind/rgw/pyproject.toml b/src/pybind/rgw/pyproject.toml
new file mode 100644
index 000000000000..2bf5ec8096be
--- /dev/null
+++ b/src/pybind/rgw/pyproject.toml
@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools", "wheel", "Cython"]
+build-backend = "setuptools.build_meta"