spatial-graph 0.0.6__tar.gz → 0.1.0__tar.gz

spatial_graph-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,202 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+    tags: [v*]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run pre-commit
+        run: pipx run pre-commit run --all-files
+
+  test:
+    name: ${{ matrix.os }} py${{ matrix.python-version }} ${{ matrix.resolution }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # ubuntu: full python range x both resolutions
+        os: [ubuntu-latest]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+        resolution: [lowest-direct, highest]
+        # windows/macos: only the endpoints, highest resolution
+        include:
+          - { os: windows-latest, python-version: "3.11", resolution: highest }
+          - { os: windows-latest, python-version: "3.14", resolution: highest }
+          - { os: macos-latest, python-version: "3.11", resolution: highest }
+          - { os: macos-latest, python-version: "3.14", resolution: highest }
+
+    env:
+      UV_RESOLUTION: ${{ matrix.resolution }}
+      # a build that silently falls back to pure-Python must fail, not go green
+      SPATIAL_GRAPH_REQUIRE_PREBUILT: "1"
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+          cache-dependency-glob: "**/pyproject.toml"
+      # --no-editable so we test the built wheel, prebuilt rtree modules and all,
+      # rather than an editable install of src/
+      - name: Install as a built wheel
+        run: uv sync --no-dev --group test --no-editable
+      - name: Test with coverage
+        run: uv run --no-sync pytest -v --cov=spatial_graph --cov-report=xml
+      - uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+
+  benchmarks:
+    runs-on: ubuntu-latest
+    env:
+      UV_NO_SYNC: "1"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.13"
+          enable-cache: true
+
+      - name: install
+        run: uv sync --no-dev --group test-codspeed --no-editable
+
+      - name: Run benchmarks
+        uses: CodSpeedHQ/action@v3
+        with:
+          run: uv run pytest -W ignore --codspeed -v --color=yes
+
+  # One abi3 wheel per platform, covering every supported CPython. Also the only
+  # thing that produces PyPI-acceptable manylinux tags -- `uv build` alone emits
+  # `linux_x86_64`, which PyPI rejects.
+  build-wheels:
+    name: Wheels ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-latest # manylinux + musllinux x86_64
+          - ubuntu-24.04-arm # manylinux + musllinux aarch64
+          - windows-latest # win_amd64 + win32
+          - macos-15-intel # macOS x86_64
+          - macos-latest # macOS arm64
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # setuptools-scm needs the tags
+      - uses: pypa/cibuildwheel@v4.1.1
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}
+          path: wheelhouse/*.whl
+
+  build-sdist:
+    name: Sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build --sdist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  # Everything else builds its own wheel; this is the only job that exercises
+  # the artifacts we would actually publish, and the only one that checks the
+  # stable-ABI claim -- one cp311 wheel running on every supported CPython.
+  test-abi3-wheel:
+    name: abi3 wheel on py${{ matrix.python-version }}
+    needs: build-wheels
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    env:
+      SPATIAL_GRAPH_REQUIRE_PREBUILT: "1"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: wheels-ubuntu-latest
+          path: wheelhouse
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      # Name the wheel directly: cibuildwheel emits a manylinux and a musllinux
+      # wheel, so a bare *.whl glob is ambiguous, while installing by package
+      # name would resolve `spatial-graph` from PyPI instead of this artifact.
+      - name: Install the built wheel with its real dependencies
+        run: |
+          uv venv
+          uv pip install wheelhouse/*manylinux*.whl pytest
+      - name: Test it
+        # test_prebuilt.py asserts the real property directly: constructing a
+        # prebuilt variant must not reach witty.compile_cython
+        run: uv run --no-sync pytest tests/test_prebuilt.py -v
+
+  deploy:
+    name: Deploy
+    needs: [test, build-wheels, build-sdist, test-abi3-wheel]
+    if: success() && startsWith(github.ref, 'refs/tags/') && github.event_name != 'schedule'
+    runs-on: ubuntu-latest
+
+    permissions:
+      id-token: write
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: wheels-*
+          path: dist
+          merge-multiple: true
+      - uses: actions/download-artifact@v4
+        with:
+          name: sdist
+          path: dist
+
+      - name: 🚢 Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+
+      - uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: "./dist/*"
+
+  docker-test:
+    name: Docker Test gxx${{ matrix.gxx_major }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        gxx_major: [14, 15]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Build and test Docker image
+        run: |
+          docker build --build-arg GXX_MAJOR=${{ matrix.gxx_major }} -t spatial_graph .
+          docker run --rm spatial_graph

{spatial_graph-0.0.6 → spatial_graph-0.1.0}/.pre-commit-config.yaml

@@ -15,13 +15,13 @@ repos:
       - id: check-added-large-files
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.15.16
+    rev: v0.16.1
     hooks:
       - id: ruff-check
         args: [--fix, --unsafe-fixes]
       - id: ruff-format
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v2.1.0
+    rev: v2.3.0
     hooks:
       - id: mypy

{spatial_graph-0.0.6 → spatial_graph-0.1.0}/PKG-INFO

@@ -1,32 +1,30 @@
 Metadata-Version: 2.4
 Name: spatial-graph
-Version: 0.0.6
+Version: 0.1.0
 Summary: A spatial graph datastructure for python.
+Author-email: Jan Funke <funkej@janelia.hhmi.org>, Talley Lambert <talley.lambert@gmail.com>
+License-Expression: MIT
 Project-URL: homepage, https://github.com/funkelab/spatial_graph
 Project-URL: repository, https://github.com/funkelab/spatial_graph
-Author-email: Jan Funke <funkej@janelia.hhmi.org>, Talley Lambert <talley.lambert@gmail.com>
-License: MIT
-License-File: LICENSE
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
-Requires-Python: >=3.10
-Requires-Dist: ct3>=3.3.3
-Requires-Dist: numpy>=1.21.2
-Requires-Dist: numpy>=1.23.2; python_version >= '3.11'
-Requires-Dist: numpy>=1.26.0; python_version >= '3.12'
-Requires-Dist: numpy>=2.1.0; python_version >= '3.13'
-Requires-Dist: numpy>=2.3.2; python_version >= '3.14'
-Requires-Dist: setuptools>=75.8.0
-Requires-Dist: typing-extensions>=4.5.0
-Requires-Dist: witty>=v0.3.0
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: witty>=0.3.2
+Requires-Dist: CT3>=3.3.3
+Requires-Dist: numpy>=2.3.2; python_version >= "3.14"
+Requires-Dist: numpy>=2.1.0; python_version >= "3.13"
+Requires-Dist: numpy>=1.26.0; python_version >= "3.12"
+Requires-Dist: numpy>=1.23.2
+Requires-Dist: setuptools>=75.8.0
+Requires-Dist: typing_extensions>=4.5.0
+Dynamic: license-file
 
 # spatial-graph
 
@@ -56,7 +54,8 @@ where each node has an nD position (in time or space).
     * attribute access
 * minimal memory footprint
 * minimal dependencies
-    * `cython` / `witty` / `cheetah3` for runtime compilation
+    * `cython` / `witty` / `cheetah3`, used only when something has to be
+      compiled at runtime (see Cross-Platform Support)
     * numpy for array interfaces
 * PYX API for graph algorithms in C/C++
 
@@ -146,16 +145,34 @@ A `SpatialGraph` consists of three data structures:
 
 ## Cross-Platform Support
 
-`spatial_graph` compiles C/C++ code at runtime, and as such needs access to a
-compiler. If you already have one, great! You can use the PyPI package.
+`spatial_graph` generates specialized C/C++ for the exact data types you ask
+for. Where those types can be known in advance we compile them ahead of time
+and ship them in the wheels; everything else is compiled on your machine the
+first time it is used, which needs a C compiler.
+
+**No compiler needed.** The PyPI wheels contain prebuilt `PointRTree` and
+`LineRTree` variants for the common combinations: `float32`/`float64`
+coordinates, 2 to 5 dimensions, and `int64`/`uint64` items -- as `int64[2]` /
+`uint64[2]` for `LineRTree`, whose items are node pairs. If your R-tree matches
+one of those -- as most do -- nothing is compiled, on any supported Python.
+
+**Compiler needed.** Two cases fall back to compiling at runtime:
+
+1. `Graph`, `DiGraph`, `SpatialGraph` and `SpatialDiGraph`. Their node and edge
+   attribute types are only known when you construct the graph, so they cannot
+   be enumerated ahead of time.
+2. R-trees outside the prebuilt set above (an `int32` item type, say, or 6
+   dimensions).
 
-If you (or your users) don't have a compiler installed, you either need to
+If you or your users need those without a compiler, you can still install
+`spatial_graph` from `conda-forge`, where we include a compiler (`clang`) in
+its dependencies.
 
-1. Install a compiler. This might be weird for non-technical users.
-2. Install `spatial_graph` from `conda-forge`, where we include a compiler
-   (`clang`) in its dependencies.
+The wheels are `abi3` (stable ABI) and require Python 3.11 or newer, so one
+wheel per platform covers every supported CPython. Python 3.10 users should
+pin to a release before this one.
 
-### Why is this so complicated?
+### Why can't everything be prebuilt?
 
 There is no cross-platform C/C++ compiler that we can install using `pip`.
 [`numba`](https://github.com/numba/numba) is maybe the closest to having solved

{spatial_graph-0.0.6 → spatial_graph-0.1.0}/README.md

@@ -26,7 +26,8 @@ where each node has an nD position (in time or space).
     * attribute access
 * minimal memory footprint
 * minimal dependencies
-    * `cython` / `witty` / `cheetah3` for runtime compilation
+    * `cython` / `witty` / `cheetah3`, used only when something has to be
+      compiled at runtime (see Cross-Platform Support)
     * numpy for array interfaces
 * PYX API for graph algorithms in C/C++
 
@@ -116,16 +117,34 @@ A `SpatialGraph` consists of three data structures:
 
 ## Cross-Platform Support
 
-`spatial_graph` compiles C/C++ code at runtime, and as such needs access to a
-compiler. If you already have one, great! You can use the PyPI package.
+`spatial_graph` generates specialized C/C++ for the exact data types you ask
+for. Where those types can be known in advance we compile them ahead of time
+and ship them in the wheels; everything else is compiled on your machine the
+first time it is used, which needs a C compiler.
 
-If you (or your users) don't have a compiler installed, you either need to
+**No compiler needed.** The PyPI wheels contain prebuilt `PointRTree` and
+`LineRTree` variants for the common combinations: `float32`/`float64`
+coordinates, 2 to 5 dimensions, and `int64`/`uint64` items -- as `int64[2]` /
+`uint64[2]` for `LineRTree`, whose items are node pairs. If your R-tree matches
+one of those -- as most do -- nothing is compiled, on any supported Python.
 
-1. Install a compiler. This might be weird for non-technical users.
-2. Install `spatial_graph` from `conda-forge`, where we include a compiler
-   (`clang`) in its dependencies.
+**Compiler needed.** Two cases fall back to compiling at runtime:
 
-### Why is this so complicated?
+1. `Graph`, `DiGraph`, `SpatialGraph` and `SpatialDiGraph`. Their node and edge
+   attribute types are only known when you construct the graph, so they cannot
+   be enumerated ahead of time.
+2. R-trees outside the prebuilt set above (an `int32` item type, say, or 6
+   dimensions).
+
+If you or your users need those without a compiler, you can still install
+`spatial_graph` from `conda-forge`, where we include a compiler (`clang`) in
+its dependencies.
+
+The wheels are `abi3` (stable ABI) and require Python 3.11 or newer, so one
+wheel per platform covers every supported CPython. Python 3.10 users should
+pin to a release before this one.
+
+### Why can't everything be prebuilt?
 
 There is no cross-platform C/C++ compiler that we can install using `pip`.
 [`numba`](https://github.com/numba/numba) is maybe the closest to having solved

{spatial_graph-0.0.6 → spatial_graph-0.1.0}/pyproject.toml

@@ -1,17 +1,34 @@
 [build-system]
-requires = ["hatchling", "hatch-vcs"]
-build-backend = "hatchling.build"
+requires = [
+  "setuptools>=77",
+  "setuptools-scm>=8",
+  "Cython>=3.1",
+  "CT3>=3.3.3",
+  "numpy",  # imported (not linked) while rendering the wrappers
+]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools_scm]
 
-[tool.hatch.version]
-source = "vcs"
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+# The JIT fallback compiles from these at runtime, so they must ship in the
+# wheel. `include-package-data` (on by default here) would pick them up from
+# the VCS/sdist manifest anyway; listing them keeps that explicit and works
+# even when no file finder is available. Patterns are package-relative, so the
+# vendored C under `_rtree/src/` and `_graph/src/` needs the `src/` prefix.
+"*" = ["py.typed", "*.pyx", "src/*.c", "src/*.h", "src/LICENSE*", "src/*.md"]
 
 [project]
 name = "spatial-graph"
 dynamic = ["version"]
 description = "A spatial graph datastructure for python."
 readme = "README.md"
-requires-python = ">=3.10"
-license = { text = "MIT" }
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
 authors = [
   { email = "funkej@janelia.hhmi.org", name = "Jan Funke" },
   { email = "talley.lambert@gmail.com", name = "Talley Lambert" },
@@ -19,8 +36,6 @@ authors = [
 classifiers = [
   "Development Status :: 3 - Alpha",
   "Intended Audience :: Developers",
-  "License :: OSI Approved :: MIT License",
-  "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
@@ -28,13 +43,12 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-  "witty>=v0.3.0",
+  "witty>=0.3.2",
   "CT3>=3.3.3",
   "numpy>=2.3.2; python_version >= '3.14'",
   "numpy>=2.1.0; python_version >= '3.13'",
   "numpy>=1.26.0; python_version >= '3.12'",
-  "numpy>=1.23.2; python_version >= '3.11'",
-  "numpy>=1.21.2",
+  "numpy>=1.23.2",
   "setuptools>=75.8.0",
   "typing_extensions>=4.5.0",  # witty<=0.3.1 imports it without declaring it
 ]
@@ -63,8 +77,18 @@ docs = [
 homepage = "https://github.com/funkelab/spatial_graph"
 repository = "https://github.com/funkelab/spatial_graph"
 
+[tool.cibuildwheel]
+# a single abi3 build per platform covers every supported CPython
+build = "cp311-*"
+# never let a wheel silently degrade to pure Python
+environment = { SPATIAL_GRAPH_REQUIRE_PREBUILT = "1" }
+test-groups = ["test"]
+# these exercise the prebuilt modules in the repaired wheel without needing a
+# compiler; cross-version and numpy-only checks live in the CI workflow
+test-command = "pytest {project}/tests/test_prebuilt.py -q"
+
 [tool.ruff]
-target-version = "py310"
+target-version = "py311"
 line-length = 88
 fix = true
 unsafe-fixes = true

spatial_graph-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

spatial_graph-0.1.0/setup.py

@@ -0,0 +1,188 @@
+"""Compile RTree variants ahead of time into a stable-ABI (abi3) wheel.
+
+Renders the same pyx wrappers the runtime would JIT-compile (via
+`_rtree._codegen`) for every variant in `iter_specs()`, so the two paths are
+generated from one source. One wheel per platform then covers every supported
+CPython, and those variants are never compiled on the user's machine -- so no
+C compiler is invoked for them.
+
+Set `SPATIAL_GRAPH_NO_PREBUILT=1` to build a pure-Python wheel instead, or
+`SPATIAL_GRAPH_REQUIRE_PREBUILT=1` (as CI does) to turn a failure to compile
+into a hard error rather than a silent fall back to JIT.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import tempfile
+import warnings
+from pathlib import Path
+
+from setuptools import Extension, setup
+
+ROOT = Path(__file__).parent
+SRC = ROOT / "src"
+PREBUILT_PKG = "spatial_graph._rtree._prebuilt"
+
+# The wrappers pass numpy arrays as typed memoryviews, which compile to
+# PyObject_GetBuffer/PyBuffer_Release. Those entered the limited API in 3.11
+# (moved from cpython/object.h, excluded under Py_LIMITED_API, to pybuffer.h),
+# so 3.11 is the floor for a stable-ABI build -- and matches requires-python.
+ABI3_MIN = (3, 11)
+ABI3_TAG = f"cp{ABI3_MIN[0]}{ABI3_MIN[1]}"
+ABI3_HEX = f"0x{ABI3_MIN[0]:02x}{ABI3_MIN[1]:02x}0000"
+
+WIN = sys.platform == "win32"
+
+
+def _src_on_path() -> None:
+    """Make the package under `src/` importable, for the helpers shared with it.
+
+    Callers import `spatial_graph` only once they know they need it: importing
+    it at module scope would make every command -- `sdist` and `egg_info`
+    included -- fail if anything the package imports is missing from the build
+    environment.
+    """
+    if str(SRC) not in sys.path:
+        sys.path.insert(0, str(SRC))
+
+
+def prebuilt_extensions() -> list[Extension]:
+    """Render every prebuilt RTree variant and declare it as an extension."""
+    from Cython.Build import cythonize
+
+    _src_on_path()
+    from spatial_graph._rtree._codegen import build_wrapper, iter_specs
+    from spatial_graph._rtree._naming import module_name
+
+    pyx_dir = ROOT / "build" / "prebuilt-pyx"
+    pyx_dir.mkdir(parents=True, exist_ok=True)
+
+    # the template `#include`s these at compile time, so they never appear in
+    # `sources`; without `depends` an edit to the C core would leave every
+    # prebuilt module stale (the JIT path declares the same set to witty)
+    rtree_dir = SRC / "spatial_graph" / "_rtree"
+    depends = [str(rtree_dir / "src" / f) for f in ("rtree.c", "rtree.h", "config.h")]
+
+    extensions = []
+    for spec in iter_specs():
+        name = module_name(spec.cls, spec.item_dtype, spec.coord_dtype, spec.dims)
+        source = build_wrapper(spec.cls, spec.item_dtype, spec.coord_dtype, spec.dims)
+        path = pyx_dir / f"{name}.pyx"
+        # only rewrite when changed, so cythonize can skip unchanged variants
+        if not path.is_file() or path.read_text() != source:
+            path.write_text(source)
+        extensions.append(
+            Extension(
+                f"{PREBUILT_PKG}.{name}",
+                sources=[str(path)],
+                depends=depends,
+                include_dirs=[str(rtree_dir)],
+                extra_compile_args=["/O2"] if WIN else ["-O3", "-Wno-unreachable-code"],
+                define_macros=[
+                    ("Py_LIMITED_API", ABI3_HEX),
+                    *([("RTREE_NOATOMICS", "1")] if WIN else []),
+                ],
+                py_limited_api=True,
+            )
+        )
+
+    return cythonize(
+        extensions,
+        language_level=3,
+        quiet=True,
+        nthreads=0 if WIN else os.cpu_count(),
+    )
+
+
+def can_compile() -> bool:
+    """Whether this machine can build a C extension at all.
+
+    Includes `Python.h` so that a box with a C compiler but no development
+    headers -- the usual shape of this failure -- is caught here rather than
+    part-way through the real build.
+    """
+    try:
+        from distutils.ccompiler import new_compiler
+        from distutils.sysconfig import customize_compiler, get_python_inc
+
+        compiler = new_compiler()
+        customize_compiler(compiler)  # picks up CC/CFLAGS, as build_ext does
+        with tempfile.TemporaryDirectory() as tmp:
+            probe = Path(tmp, "probe.c")
+            probe.write_text("#include <Python.h>\nint main(void) { return 0; }\n")
+            # mirror build_ext, which passes both include dirs when the
+            # platform-specific one differs (that is where pyconfig.h can live)
+            includes = [get_python_inc()]
+            if (plat_inc := get_python_inc(plat_specific=True)) not in includes:
+                includes.append(plat_inc)
+            compiler.compile([str(probe)], output_dir=tmp, include_dirs=includes)
+    except Exception:
+        return False
+    return True
+
+
+# Rendering and cythonizing every variant is wasted work for commands that only
+# want metadata -- without this, `build --sdist` pays for a full codegen pass.
+METADATA_ONLY = {"egg_info", "dist_info", "sdist"}
+NEEDS_EXTENSIONS = {
+    "bdist_egg",
+    "bdist_wheel",
+    "build",
+    "build_ext",
+    "build_py",
+    "develop",
+    "editable_wheel",
+    "install",
+}
+
+
+def metadata_only() -> bool:
+    """Whether this invocation asks for nothing that needs the extensions.
+
+    Matches on recognized command names only, so option values (`--dist-dir
+    /tmp/x`) are ignored, and anything unrecognized falls through to building
+    -- skipping wrongly would silently yield a wheel with no prebuilt modules.
+    """
+    seen = {arg for arg in sys.argv[1:] if arg in METADATA_ONLY | NEEDS_EXTENSIONS}
+    return bool(seen) and seen <= METADATA_ONLY
+
+
+def should_prebuild() -> bool:
+    """Whether to compile prebuilt variants into this wheel."""
+    if metadata_only():
+        return False
+
+    _src_on_path()
+    from spatial_graph._rtree._naming import env_enabled
+
+    if env_enabled("SPATIAL_GRAPH_NO_PREBUILT"):
+        return False
+    if env_enabled("SPATIAL_GRAPH_REQUIRE_PREBUILT"):
+        return True  # CI: never let a build silently degrade
+    if can_compile():
+        return True
+    # Installing from an sdist without a compiler must keep working: fall back to
+    # a pure-Python wheel that JIT-compiles on first use, as it did before
+    # prebuilding existed.
+    warnings.warn(
+        "No usable C compiler found; building spatial-graph without prebuilt "
+        "rtree modules. A C compiler will be needed the first time an RTree is "
+        "used.",
+        stacklevel=1,
+    )
+    return False
+
+
+if __name__ == "__main__":
+    if should_prebuild():
+        setup(
+            ext_modules=prebuilt_extensions(),
+            options={
+                "bdist_wheel": {"py_limited_api": ABI3_TAG},
+                "build_ext": {"parallel": os.cpu_count()},
+            },
+        )
+    else:
+        setup(ext_modules=[])