fastquadtree 2.3.0__tar.gz → 2.4.1__tar.gz

{fastquadtree-2.3.0 → fastquadtree-2.4.1}/.github/workflows/docs.yml

@@ -13,14 +13,14 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
           fetch-tags: true
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with: { python-version: '3.11' }
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@v8.1.0
         with:
           enable-cache: true
       - run: uv sync --group dev --group docs

{fastquadtree-2.3.0 → fastquadtree-2.4.1}/.github/workflows/release.yml

@@ -12,15 +12,15 @@ jobs:
     name: Test build
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.9"
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@v8.1.0
         with:
           enable-cache: true
 
@@ -45,7 +45,7 @@ jobs:
         run: cargo test
 
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@v6
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
 
@@ -78,42 +78,87 @@ jobs:
             manylinux: "2_28"
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       # Keep Python simple here; maturin-action brings its own Python(s) for builds.
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.9"
 
       - name: Build wheels with maturin
-        uses: PyO3/maturin-action@v1
+        uses: PyO3/maturin-action@v1.51.0
         with:
           command: build
           args: ${{ matrix.maturin_args }}
           manylinux: ${{ matrix.manylinux }}
 
       - name: Upload dist artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: dist-${{ runner.os }}-${{ matrix.maturin_args }}
           path: dist/*
 
+  build_pyodide:
+    name: Build Pyodide wheel
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+        with:
+          enable-cache: true
+
+      - name: Install pyodide CLI
+        run: uv tool install pyodide-cli --with pyodide-build
+
+      - name: Cache Pyodide cross-build environment
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/fastquadtree-pyodide
+          key: pyodide-xbuildenv-${{ runner.os }}-20260401-1.93.0
+
+      - name: Build Pyodide wheel
+        env:
+          PYODIDE_XBUILDENV_ROOT: ~/.cache/fastquadtree-pyodide
+          PYODIDE_ENV_VERSION: "20260401"
+          RUST_TOOLCHAIN: "1.93.0"
+          UV_CACHE_DIR: ~/.cache/uv
+        run: bash scripts/build_pyodide_wheel.sh
+
+      - name: Upload Pyodide dist artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: dist-pyodide
+          path: dist/*pyemscripten*_wasm32.whl
+
   publish:
     name: Publish distributions to PyPI
-    needs: build
+    needs: [build, build_pyodide]
     runs-on: ubuntu-latest
     permissions:
       contents: read
       id-token: write # for Trusted Publisher (recommended)
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@v8.1.0
 
       - name: Download all dist artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           pattern: dist-*
           path: dist

{fastquadtree-2.3.0 → fastquadtree-2.4.1}/.github/workflows/test.yml

@@ -13,16 +13,16 @@ jobs:
         python-version: ["3.9", "3.14"]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
           allow-prereleases: true
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@v8.1.0
         with:
           enable-cache: true
 
@@ -49,6 +49,6 @@ jobs:
         run: cargo test
 
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@v6
         with:
           token: ${{ secrets.CODECOV_TOKEN }}

{fastquadtree-2.3.0 → fastquadtree-2.4.1}/.gitignore

@@ -216,4 +216,7 @@ __marimo__/
 *.exe 
 *.pdb
 *.bin
-*.lock
+*.lock
+
+# pyodide
+.pyodide*

{fastquadtree-2.3.0 → fastquadtree-2.4.1}/.pre-commit-config.yaml

@@ -1,7 +1,7 @@
 repos:
   # 0) Python linter and formatter: Ruff
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.6.9
+    rev: v0.15.15
     hooks:
       # Lint + autofix. If Ruff fixes something, the hook exits nonzero to force a re-run.
       - id: ruff

{fastquadtree-2.3.0 → fastquadtree-2.4.1}/Cargo.lock

@@ -44,7 +44,7 @@ dependencies = [
 
 [[package]]
 name = "fastquadtree"
-version = "2.3.0"
+version = "2.4.1"
 dependencies = [
  "num-traits",
  "numpy",

{fastquadtree-2.3.0 → fastquadtree-2.4.1}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "fastquadtree"
-version = "2.3.0"
+version = "2.4.1"
 edition = "2021"
 rust-version = "1.89"
 readme = "README.md"

{fastquadtree-2.3.0 → fastquadtree-2.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastquadtree
-Version: 2.3.0
+Version: 2.4.1
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.9
@@ -62,7 +62,7 @@ Rust-optimized quadtree with a clean Python API
 - Support for [inserting bounding boxes](https://elan456.github.io/fastquadtree/api/rect_quadtree/) or points
 - Fast KNN and range queries
 - Optional object tracking for id ↔ object mapping
-- Mostly drop-in [pygame sprite-group integration](https://elan456.github.io/fastquadtree/api/pygame/) that adds automatic broadphase culling for faster collision detection (depending on workload)
+- Mostly drop-in [pygame sprite-group integration](https://elan456.github.io/fastquadtree/api/pygame/) that adds automatic broadphase culling plus rect queries and k-NN over sprite rects
 - Fast [serialization](https://elan456.github.io/fastquadtree/benchmark/#serialization-vs-rebuild) to/from bytes
 - Support for multiple data types (f32, f64, i32, i64) for coordinates
 - [100% test coverage](https://codecov.io/gh/Elan456/fastquadtree) and CI on GitHub Actions
@@ -89,7 +89,7 @@ from fastquadtree.pyqtree import Index  # Drop-in pyqtree shim (~10x faster whil
 | `QuadTreeObjects` | Points | Yes | Point indexing with attached Python objects. |
 | `RectQuadTreeObjects` | Bounding boxes | Yes | Rectangle indexing with attached objects. |
 | `fastquadtree.pyqtree.Index` | Bounding boxes | Yes | pyqtree-compatible API, much faster. |
-| `fastquadtree.pygame.Group` | pygame sprites | Yes | Mostly drop-in replacement for `pygame.sprite.Group` with quadtree indexing for faster collision detection. |
+| `fastquadtree.pygame.Group` | pygame sprites | Yes | Mostly drop-in `Group` with sprite queries. |
 
 
 ## Quickstart
@@ -173,7 +173,7 @@ See the [benchmark section](https://elan456.github.io/fastquadtree/benchmark/) f
 
 * `bounds` — tuple `(min_x, min_y, max_x, max_y)` defines the 2D area covered by the quadtree
 * `capacity` — max number of points kept in a leaf before splitting
-* `max_depth` — optional depth cap. If omitted, the tree can keep splitting as needed
+* `max_depth` — optional depth cap. If omitted, uses the [engine default](https://elan456.github.io/fastquadtree/engine_defaults/#max-depth)
 * `dtype` — data type for coordinates, e.g., `"f32"`, `"f64"`, `"i32"`, `"i64"`
 
 ### Key Methods

{fastquadtree-2.3.0 → fastquadtree-2.4.1}/README.md

@@ -32,7 +32,7 @@ Rust-optimized quadtree with a clean Python API
 - Support for [inserting bounding boxes](https://elan456.github.io/fastquadtree/api/rect_quadtree/) or points
 - Fast KNN and range queries
 - Optional object tracking for id ↔ object mapping
-- Mostly drop-in [pygame sprite-group integration](https://elan456.github.io/fastquadtree/api/pygame/) that adds automatic broadphase culling for faster collision detection (depending on workload)
+- Mostly drop-in [pygame sprite-group integration](https://elan456.github.io/fastquadtree/api/pygame/) that adds automatic broadphase culling plus rect queries and k-NN over sprite rects
 - Fast [serialization](https://elan456.github.io/fastquadtree/benchmark/#serialization-vs-rebuild) to/from bytes
 - Support for multiple data types (f32, f64, i32, i64) for coordinates
 - [100% test coverage](https://codecov.io/gh/Elan456/fastquadtree) and CI on GitHub Actions
@@ -59,7 +59,7 @@ from fastquadtree.pyqtree import Index  # Drop-in pyqtree shim (~10x faster whil
 | `QuadTreeObjects` | Points | Yes | Point indexing with attached Python objects. |
 | `RectQuadTreeObjects` | Bounding boxes | Yes | Rectangle indexing with attached objects. |
 | `fastquadtree.pyqtree.Index` | Bounding boxes | Yes | pyqtree-compatible API, much faster. |
-| `fastquadtree.pygame.Group` | pygame sprites | Yes | Mostly drop-in replacement for `pygame.sprite.Group` with quadtree indexing for faster collision detection. |
+| `fastquadtree.pygame.Group` | pygame sprites | Yes | Mostly drop-in `Group` with sprite queries. |
 
 
 ## Quickstart
@@ -143,7 +143,7 @@ See the [benchmark section](https://elan456.github.io/fastquadtree/benchmark/) f
 
 * `bounds` — tuple `(min_x, min_y, max_x, max_y)` defines the 2D area covered by the quadtree
 * `capacity` — max number of points kept in a leaf before splitting
-* `max_depth` — optional depth cap. If omitted, the tree can keep splitting as needed
+* `max_depth` — optional depth cap. If omitted, uses the [engine default](https://elan456.github.io/fastquadtree/engine_defaults/#max-depth)
 * `dtype` — data type for coordinates, e.g., `"f32"`, `"f64"`, `"i32"`, `"i64"`
 
 ### Key Methods

{fastquadtree-2.3.0 → fastquadtree-2.4.1}/benchmarks/benchmark_np_vs_list.py

@@ -38,9 +38,9 @@ def _build_tree_np(points_np: np.ndarray) -> float:
     # Direct NumPy path
     inserted = qt.insert_many_np(points_np)
     dt = now() - t0
-    assert (
-        inserted.count == points_np.shape[0]
-    ), f"Inserted {inserted} != {points_np.shape[0]}"
+    assert inserted.count == points_np.shape[0], (
+        f"Inserted {inserted} != {points_np.shape[0]}"
+    )
     return dt
 
 
@@ -49,9 +49,9 @@ def _build_tree_list(points_list: list[tuple[float, float]]) -> float:
     qt = ShimQuadTree(BOUNDS, CAPACITY, max_depth=MAX_DEPTH)
     inserted = qt.insert_many(points_list)
     dt = now() - t0
-    assert inserted.count == len(
-        points_list
-    ), f"Inserted {inserted} != {len(points_list)}"
+    assert inserted.count == len(points_list), (
+        f"Inserted {inserted} != {len(points_list)}"
+    )
     return dt
 
 

fastquadtree-2.4.1/docs/api/pygame.md

@@ -0,0 +1,8 @@
+# fastquadtree.pygame
+
+!!! note "Optional dependency"
+    Core `fastquadtree` APIs do not require pygame. This page documents the
+    optional `fastquadtree.pygame` integration, which requires pygame or a
+    compatible package such as `pygame-ce` when imported at runtime.
+
+::: fastquadtree.pygame

fastquadtree-2.4.1/docs/engine_defaults.md

@@ -0,0 +1,73 @@
+# Engine Defaults
+
+## max_depth {#max-depth}
+
+When `max_depth=None`, the native Python APIs use a dtype-specific engine
+default. These defaults apply to `QuadTree`, `RectQuadTree`,
+`QuadTreeObjects`, `RectQuadTreeObjects`, and the `fastquadtree.pygame`
+integration when `max_depth` is omitted.
+
+| dtype | Engine default `max_depth` |
+|---|---:|
+| `f32` | 24 |
+| `f64` | 53 |
+| `i32` | 32 |
+| `i64` | 64 |
+
+Use `get_inner_max_depth()` on a constructed tree to inspect the resolved
+engine value.
+
+### Why These Values?
+
+Infinite subdivision was the default behavior prior to version 1.4.3. With
+infinite subdivision, inserting two points at the same location could keep
+splitting forever and eventually exhaust memory, as seen in
+[issue #10](https://github.com/Elan456/fastquadtree/issues/10). The engine
+default now caps subdivision before it can become unbounded.
+
+One alternative would be for the engine to check for duplicate coordinates
+before splitting. However, doing so would add work to each insert and make
+splitting behavior harder to define for cells that contain a mixture of
+duplicate and nearby non-duplicate points. Letting duplicated points create a
+depth of 24 or 53 in some parts of the tree can also hurt traversal time, so the
+default is a compromise rather than a perfect answer for every workload.
+
+The default caps are based on a practical starting point for each dtype. Each
+quadtree level halves a node's width and height:
+
+```text
+cell_width_at_depth_d  = world_width / 2^d
+cell_height_at_depth_d = world_height / 2^d
+```
+
+The chosen defaults are roughly aligned with the binary precision available for
+each coordinate type:
+
+- `f32` uses 24 because single-precision floats have about 24 bits of
+  significand precision.
+- `f64` uses 53 because double-precision floats have about 53 bits of
+  significand precision.
+- `i32` uses 32 and `i64` uses 64 because integer coordinates cannot provide
+  more distinct binary subdivision steps than their bit width.
+
+These values are safety defaults, not hard limits on useful subdivision. World
+size and data distribution still matter. For example, with `f32` and a world
+width of `1_000_000_000`, depth 24 still leaves cells about 60 units wide:
+
+```text
+1_000_000_000 / 2^24 ~= 59.6
+```
+
+If most of your points are clustered near the origin and you need to separate
+features smaller than that, more than 24 splits can still be meaningful. In that
+case, pass an explicit `max_depth` larger than the engine default.
+
+For `i32` and `i64`, there is generally no situation where you would need more
+than 32 and 64 subdivisions, respectively.
+
+The defaults are intended to be a relatively safe starting point. Use tighter
+world bounds, coordinate normalization, or an explicit `max_depth` when your
+world is very large compared with the area where points actually cluster.
+
+For best performance, choose a `max_depth` that keeps leaf cells near the scale
+of your typical queries and data spacing.

{fastquadtree-2.3.0 → fastquadtree-2.4.1}/docs/index.md

@@ -41,7 +41,7 @@
 - Support for [inserting bounding boxes](api/rect_quadtree.md) or points
 - Fast KNN and range queries
 - Optional object tracking for id ↔ object mapping
-- Mostly drop-in [pygame sprite-group integration](api/pygame.md) that adds automatic broadphase culling for faster collision detection (depending on workload)
+- Mostly drop-in [pygame sprite-group integration](api/pygame.md) that adds automatic broadphase culling plus rect queries and k-NN over sprite rects
 - Fast [serialization](benchmark.md#serialization-vs-rebuild) to/from bytes
 - Support for multiple data types (f32, f64, i32, i64) for coordinates
 - [100% test coverage](https://codecov.io/gh/Elan456/fastquadtree) and CI on GitHub Actions
@@ -63,5 +63,5 @@ from fastquadtree import RectQuadTree  # Bounding box handling
 from fastquadtree import QuadTreeObjects  # Point handling with object tracking
 from fastquadtree import RectQuadTreeObjects  # Bounding box handling with object tracking
 from fastquadtree.pyqtree import Index # Drop-in replacement for pyqtree (~10x faster while keeping the same API)
-from fastquadtree.pygame import Group # Mostly drop-in replacement for pygame.sprite.Group with quadtree indexing (pygame install required)
+from fastquadtree.pygame import Group # Mostly drop-in pygame Group with quadtree queries (pygame install required)
 ```

{fastquadtree-2.3.0 → fastquadtree-2.4.1}/docs/quickstart.md

@@ -103,15 +103,16 @@ Tip: Use `QuadTree` instead of `QuadTreeObjects` for max speed when you do not n
 
 ---
 
-## Pygame sprite groups
+## Pygame sprite groups and spatial queries
 
-The optional `fastquadtree.pygame` module provides a mostly drop-in
-`pygame.sprite.Group` replacement plus collision helpers shaped like pygame's
-own `spritecollide(...)` APIs. It indexes sprite `rect` bounds to give you
-automatic broadphase culling for collision queries and viewport culling.
+The optional `fastquadtree.pygame` module provides a pygame sprite group backed
+by `RectQuadTreeObjects`. It supports normal sprite-group operations, collision
+helpers shaped like pygame's own `spritecollide(...)` APIs, and direct spatial
+queries such as rectangle queries and k-nearest-neighbor search over sprite
+`rect` bounds.
 
 This is most useful when you have many static or mostly stable sprites and each
-query touches only a small part of the world. The tradeoff is tree maintenance:
+query touches only a small part of the world. The tradeoff is index maintenance:
 moving indexed sprites need `Group.update(...)` or `Group.sync(...)` so the
 index reflects their current rects. If most sprites move every frame, create the
 group with `rebuild_on_update=True` to rebuild the index after each
@@ -124,14 +125,20 @@ import fastquadtree.pygame as fpygame
 world_bounds = (0, 0, 2000, 2000)
 blocks = fpygame.Group(bounds=world_bounds)
 blocks.add(block_sprites)
+blocks.add(enemy_sprite)
 
 # Collision helper with the same shape as pygame.sprite.spritecollide.
 hits = fpygame.spritecollide(player, blocks, dokill=False)
 
 # Rectangle queries can use pygame.Rect or (min_x, min_y, max_x, max_y) bounds.
-visible = blocks.query_rect(camera_rect, sync=False)
+visible = blocks.query(camera_rect, sync=False)
 for sprite in visible:
     screen.blit(sprite.image, sprite.rect.move(-camera_x, -camera_y))
+
+# Direct spatial queries return sprites.
+nearest = blocks.nearest_neighbors(player.rect.center, k=5)
+for sprite in nearest:
+    print(sprite)
 ```
 
 pygame is not a required dependency for core `fastquadtree`; install a

{fastquadtree-2.3.0 → fastquadtree-2.4.1}/docs/runnables.md

@@ -62,7 +62,7 @@ uv run python interactive/ballpit.py
 ![Ballpit_Demo_Screenshot](https://raw.githubusercontent.com/Elan456/fastquadtree/main/assets/ballpit.png)
 
 ## 3. Pygame sprite group comparison
-- Compare `pygame.sprite.Group` with the mostly drop-in `fastquadtree.pygame.Group`
+- Compare `pygame.sprite.Group` with the quadtree-backed `fastquadtree.pygame.Group`
 - Press `G` to switch group backends while the demo is running
 - Uses the fastquadtree-backed group for automatic broadphase culling
 
@@ -70,7 +70,7 @@ This demo creates many static block sprites and a moving player. Player
 collision uses the normal `spritecollide(...)` flow for both backends. Viewport
 culling asks "which blocks intersect the camera rect?" The pygame backend
 answers by scanning every block, while the fastquadtree backend can answer the
-same rectangle query through `Group.query_rect(...)`.
+same rectangle query through `Group.query(...)`.
 
 The performance tradeoff is tree maintenance. The demo uses static blocks, so
 the fastquadtree group can reuse its index frame after frame. If most indexed

{fastquadtree-2.3.0 → fastquadtree-2.4.1}/mkdocs.yml

@@ -87,6 +87,7 @@ nav:
   - Benchmark: benchmark.md
   - Future Features: future_features.md
   - Rust Usage: rust_usage.md
+  - Engine Defaults: engine_defaults.md
   - API:
       - QuadTree: api/quadtree.md
       - RectQuadTree: api/rect_quadtree.md

{fastquadtree-2.3.0 → fastquadtree-2.4.1}/pyproject.toml

@@ -53,7 +53,7 @@ compatibility = "manylinux_2_28"
 # uv sync will install the "dev" group by default.
 [dependency-groups]
 dev = [  # Testing and build dependencies
-  "ruff>=0.6.0",
+  "ruff>=0.15.15",
   "pytest>=8.4.2",
   "pytest-cov>=7.0.0",
   "coverage>=7.5",

{fastquadtree-2.3.0 → fastquadtree-2.4.1}/pysrc/fastquadtree/_base_quadtree.py

@@ -296,7 +296,8 @@ class _BaseQuadTree(Generic[G], ABC):
         """
         Return the maximum depth of the quadtree.
 
-        Useful if you constructed with max_depth=None.
+        Useful if you constructed with max_depth=None and want to inspect the
+        resolved engine default.
         """
         return self._native.get_max_depth()
 

{fastquadtree-2.3.0 → fastquadtree-2.4.1}/pysrc/fastquadtree/_base_quadtree_objects.py

@@ -692,7 +692,8 @@ class _BaseQuadTreeObjects(Generic[G, ItemType], ABC):
         """
         Return the maximum depth of the quadtree.
 
-        Useful if you constructed with max_depth=None.
+        Useful if you constructed with max_depth=None and want to inspect the
+        resolved engine default.
         """
         return self._native.get_max_depth()
 

{fastquadtree-2.3.0 → fastquadtree-2.4.1}/pysrc/fastquadtree/point_quadtree.py

@@ -29,7 +29,8 @@ class QuadTree(_BaseQuadTree[Point]):
     Args:
         bounds: World bounds as (min_x, min_y, max_x, max_y).
         capacity: Maximum points per node before splitting.
-        max_depth: Optional maximum tree depth (uses engine default if not specified).
+        max_depth: Optional maximum tree depth. If omitted, uses the
+            [engine default](https://elan456.github.io/fastquadtree/engine_defaults/#max-depth).
         dtype: Coordinate data type ('f32', 'f64', 'i32', 'i64'). Default: 'f32'.
 
     Performance:

{fastquadtree-2.3.0 → fastquadtree-2.4.1}/pysrc/fastquadtree/point_quadtree_objects.py

@@ -28,7 +28,8 @@ class QuadTreeObjects(_BaseQuadTreeObjects[Point, PointItem]):
     Args:
         bounds: World bounds as (min_x, min_y, max_x, max_y).
         capacity: Maximum points per node before splitting.
-        max_depth: Optional maximum tree depth (uses engine default if not specified).
+        max_depth: Optional maximum tree depth. If omitted, uses the
+            [engine default](https://elan456.github.io/fastquadtree/engine_defaults/#max-depth).
         dtype: Coordinate data type ('f32', 'f64', 'i32', 'i64'). Default: 'f32'.
 
     Performance: