fastquadtree 2.2.0__tar.gz → 2.4.0__tar.gz

{fastquadtree-2.2.0 → fastquadtree-2.4.0}/.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.2.0 → fastquadtree-2.4.0}/Cargo.lock

@@ -9,35 +9,48 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c08606f8c3cbf4ce6ec8e28fb0014a2c086708fe954eaa885384a6165172e7e8"
 
 [[package]]
-name = "bincode"
-version = "2.0.1"
+name = "darling"
+version = "0.23.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "36eaf5d7b090263e8150820482d5d93cd964a81e4019913c972f4edcc6edb740"
+checksum = "25ae13da2f202d56bd7f91c25fba009e7717a1e4a1cc98a76d844b65ae912e9d"
 dependencies = [
- "bincode_derive",
- "serde",
- "unty",
+ "darling_core",
+ "darling_macro",
 ]
 
 [[package]]
-name = "bincode_derive"
-version = "2.0.1"
+name = "darling_core"
+version = "0.23.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bf95709a440f45e986983918d0e8a1f30a9b1df04918fc828670606804ac3c09"
+checksum = "9865a50f7c335f53564bb694ef660825eb8610e0a53d3e11bf1b0d3df31e03b0"
 dependencies = [
- "virtue",
+ "ident_case",
+ "proc-macro2",
+ "quote",
+ "strsim",
+ "syn",
+]
+
+[[package]]
+name = "darling_macro"
+version = "0.23.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ac3984ec7bd6cfa798e62b4a642426a5be0e68f9401cfc2a01e3fa9ea2fcdb8d"
+dependencies = [
+ "darling_core",
+ "quote",
+ "syn",
 ]
 
 [[package]]
 name = "fastquadtree"
-version = "2.2.0"
+version = "2.4.0"
 dependencies = [
- "bincode",
  "num-traits",
  "numpy",
  "pyo3",
- "serde",
  "smallvec",
+ "wincode",
 ]
 
 [[package]]
@@ -46,6 +59,12 @@ version = "0.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
 
+[[package]]
+name = "ident_case"
+version = "1.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b9e0384b61958566e926dc50660321d12159025e767c18e043daf26b70104c39"
+
 [[package]]
 name = "libc"
 version = "0.2.186"
@@ -126,6 +145,12 @@ version = "1.21.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
 
+[[package]]
+name = "pastey"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2ee67f1008b1ba2321834326597b8e186293b049a023cdef258527550b9935b4"
+
 [[package]]
 name = "portable-atomic"
 version = "1.13.1"
@@ -230,57 +255,53 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "94300abf3f1ae2e2b8ffb7b58043de3d399c73fa6f4b73826402a5c457614dbe"
 
 [[package]]
-name = "serde"
-version = "1.0.228"
+name = "smallvec"
+version = "1.15.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e"
-dependencies = [
- "serde_core",
- "serde_derive",
-]
+checksum = "67b1b7a3b5fe4f1376887184045fcf45c69e92af734b7aaddc05fb777b6fbd03"
 
 [[package]]
-name = "serde_core"
-version = "1.0.228"
+name = "strsim"
+version = "0.11.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad"
-dependencies = [
- "serde_derive",
-]
+checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"
 
 [[package]]
-name = "serde_derive"
-version = "1.0.228"
+name = "syn"
+version = "2.0.117"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79"
+checksum = "e665b8803e7b1d2a727f4023456bbbbe74da67099c585258af0ad9c5013b9b99"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "unicode-ident",
 ]
 
 [[package]]
-name = "smallvec"
-version = "1.15.1"
+name = "target-lexicon"
+version = "0.13.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "67b1b7a3b5fe4f1376887184045fcf45c69e92af734b7aaddc05fb777b6fbd03"
+checksum = "adb6935a6f5c20170eeceb1a3835a49e12e19d792f6dd344ccc76a985ca5a6ca"
 
 [[package]]
-name = "syn"
-version = "2.0.117"
+name = "thiserror"
+version = "2.0.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e665b8803e7b1d2a727f4023456bbbbe74da67099c585258af0ad9c5013b9b99"
+checksum = "4288b5bcbc7920c07a1149a35cf9590a2aa808e0bc1eafaade0b80947865fbc4"
 dependencies = [
- "proc-macro2",
- "quote",
- "unicode-ident",
+ "thiserror-impl",
 ]
 
 [[package]]
-name = "target-lexicon"
-version = "0.13.5"
+name = "thiserror-impl"
+version = "2.0.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "adb6935a6f5c20170eeceb1a3835a49e12e19d792f6dd344ccc76a985ca5a6ca"
+checksum = "ebc4ee7f67670e9b64d05fa4253e753e016c6c95ff35b89b7941d6b856dec1d5"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
 
 [[package]]
 name = "unicode-ident"
@@ -289,13 +310,26 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
 
 [[package]]
-name = "unty"
-version = "0.0.4"
+name = "wincode"
+version = "0.5.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6d49784317cd0d1ee7ec5c716dd598ec5b4483ea832a2dced265471cc0f690ae"
+checksum = "66d967db7705dc29120bb6e8ce5b5a2e27734ed5976d1c904e95bd238d1c3c5a"
+dependencies = [
+ "pastey",
+ "proc-macro2",
+ "quote",
+ "thiserror",
+ "wincode-derive",
+]
 
 [[package]]
-name = "virtue"
-version = "0.0.18"
+name = "wincode-derive"
+version = "0.4.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "051eb1abcf10076295e815102942cc58f9d5e3b4560e46e53c21e8ff6f3af7b1"
+checksum = "15ab90b719560d0fda79c74550ad1c948d17b118765942838055ebaf34d67071"
+dependencies = [
+ "darling",
+ "proc-macro2",
+ "quote",
+ "syn",
+]

{fastquadtree-2.2.0 → fastquadtree-2.4.0}/Cargo.toml

@@ -1,7 +1,8 @@
 [package]
 name = "fastquadtree"
-version = "2.2.0"
+version = "2.4.0"
 edition = "2021"
+rust-version = "1.89"
 readme = "README.md"
 
 [lib]
@@ -11,8 +12,7 @@ crate-type = ["rlib", "cdylib"]
 pyo3 = { version = "0.28", features = ["extension-module", "abi3-py39"] }
 smallvec = "1.15.1"
 numpy = "0.28"
-serde = { version = "1.0", features = ["derive"] }
-bincode = {version = "2.0.1", features = ["serde"]}
+wincode = { version = "0.5.5", features = ["derive"] }
 num-traits = "0.2"
 
 [profile.release]

{fastquadtree-2.2.0 → fastquadtree-2.4.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Ethan Anderson
+Copyright (c) 2025-2026 Ethan Anderson
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{fastquadtree-2.2.0 → fastquadtree-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastquadtree
-Version: 2.2.0
+Version: 2.4.0
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.9
@@ -62,6 +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 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
@@ -88,6 +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 `Group` with sprite queries. |
 
 
 ## Quickstart
@@ -171,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
@@ -233,7 +235,9 @@ qt.insert_many_np(points)  # Use insert_many_np for NumPy arrays
 ```
 
 **Does fastquadtree support multiprocessing?**
-Yes, fastquadtree objects can be serialized to bytes using the `to_bytes()` method and deserialized back using `from_bytes()`. This allows you to share quadtree data across processes and even cache prebuilt trees to disk. When using `QuadTreeObjects` or `RectQuadTreeObjects`, you must pass `include_objects=True` to `to_bytes()` to serialize Python objects, and `allow_objects=True` to `from_bytes()` when loading. By default, objects are skipped for safety, as deserializing untrusted Python objects can be unsafe. See the [interactive v2 demo](https://github.com/Elan456/fastquadtree/blob/main/interactive/interactive_v2.py) for an example of saving and loading a quadtree, and the [QuadTreeObjects API docs](https://elan456.github.io/fastquadtree/api/quadtree_objects/#fastquadtree.QuadTreeObjects.to_bytes) for full details on the serialization methods.
+Yes, fastquadtree objects can be serialized to bytes using the `to_bytes()` method and deserialized back using `from_bytes()`. This allows you to share quadtree data across processes and even cache prebuilt trees to disk. When using `QuadTreeObjects` or `RectQuadTreeObjects`, you must pass `include_objects=True` to `to_bytes()` to serialize Python objects, and `allow_objects=True` to `from_bytes()` when loading. By default, objects are skipped for safety, as deserializing untrusted Python objects can be unsafe. Native decode uses a default preallocation limit of 67,108,864 bytes (64 MiB); if loading needs more than the configured bucket, `from_bytes()` fails with a `ValueError` unless you choose a larger allowed bucket or pass `disable_preallocation_limit=True` for trusted data. See the [interactive v2 demo](https://github.com/Elan456/fastquadtree/blob/main/interactive/interactive_v2.py) for an example of saving and loading a quadtree, and the [QuadTreeObjects API docs](https://elan456.github.io/fastquadtree/api/quadtree_objects/#fastquadtree.QuadTreeObjects.to_bytes) for full details on the serialization methods.
+
+Serialization uses the current fastquadtree binary format. Data serialized by bincode-backed fastquadtree releases, including v2.2 and earlier, is not loadable by newer wincode-backed releases.
 
 ## License
 

{fastquadtree-2.2.0 → fastquadtree-2.4.0}/README.md

@@ -32,6 +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 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
@@ -58,6 +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 `Group` with sprite queries. |
 
 
 ## Quickstart
@@ -141,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
@@ -203,7 +205,9 @@ qt.insert_many_np(points)  # Use insert_many_np for NumPy arrays
 ```
 
 **Does fastquadtree support multiprocessing?**
-Yes, fastquadtree objects can be serialized to bytes using the `to_bytes()` method and deserialized back using `from_bytes()`. This allows you to share quadtree data across processes and even cache prebuilt trees to disk. When using `QuadTreeObjects` or `RectQuadTreeObjects`, you must pass `include_objects=True` to `to_bytes()` to serialize Python objects, and `allow_objects=True` to `from_bytes()` when loading. By default, objects are skipped for safety, as deserializing untrusted Python objects can be unsafe. See the [interactive v2 demo](https://github.com/Elan456/fastquadtree/blob/main/interactive/interactive_v2.py) for an example of saving and loading a quadtree, and the [QuadTreeObjects API docs](https://elan456.github.io/fastquadtree/api/quadtree_objects/#fastquadtree.QuadTreeObjects.to_bytes) for full details on the serialization methods.
+Yes, fastquadtree objects can be serialized to bytes using the `to_bytes()` method and deserialized back using `from_bytes()`. This allows you to share quadtree data across processes and even cache prebuilt trees to disk. When using `QuadTreeObjects` or `RectQuadTreeObjects`, you must pass `include_objects=True` to `to_bytes()` to serialize Python objects, and `allow_objects=True` to `from_bytes()` when loading. By default, objects are skipped for safety, as deserializing untrusted Python objects can be unsafe. Native decode uses a default preallocation limit of 67,108,864 bytes (64 MiB); if loading needs more than the configured bucket, `from_bytes()` fails with a `ValueError` unless you choose a larger allowed bucket or pass `disable_preallocation_limit=True` for trusted data. See the [interactive v2 demo](https://github.com/Elan456/fastquadtree/blob/main/interactive/interactive_v2.py) for an example of saving and loading a quadtree, and the [QuadTreeObjects API docs](https://elan456.github.io/fastquadtree/api/quadtree_objects/#fastquadtree.QuadTreeObjects.to_bytes) for full details on the serialization methods.
+
+Serialization uses the current fastquadtree binary format. Data serialized by bincode-backed fastquadtree releases, including v2.2 and earlier, is not loadable by newer wincode-backed releases.
 
 ## License
 

{fastquadtree-2.2.0 → fastquadtree-2.4.0}/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.2.0 → fastquadtree-2.4.0}/docs/2.0_migration_guide.md

@@ -288,6 +288,8 @@ rqt_obj.update(id_, new_min_x, new_min_y, new_max_x, new_max_y)
 
 The serialization format has changed. **v1 serialized data cannot be loaded in v2.**
 
+The native core codec changed again after v2.2 from bincode to wincode. Bincode-backed serialized data from fastquadtree v2.2 and earlier is not loadable by newer wincode-backed releases.
+
 ### Before (v1.x)
 
 ```python
@@ -455,4 +457,4 @@ from fastquadtree import (
     PointItem,
     RectItem,
 )
-```
+```

fastquadtree-2.4.0/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.2.0 → fastquadtree-2.4.0}/docs/benchmark.md

@@ -132,22 +132,22 @@ If your data is already in a NumPy array, using the `insert_many_np` method dire
 
 | Variant | Mean (s) | Stdev (s) |
 |---|---:|---:|
-| Serialize to bytes | 0.021356 | 0.000937 |
-| Rebuild from points | 0.106783 | 0.011430 |
-| Rebuild from bytes | 0.021754 | 0.001687 |
-| Rebuild from file | 0.024887 | 0.001846 |
+| Serialize to bytes | 0.011789 | 0.000617 |
+| Rebuild from points | 0.088791 | 0.001616 |
+| Rebuild from bytes | 0.007105 | 0.000137 |
+| Rebuild from file | 0.012052 | 0.000442 |
 
 ### Summary
 
-- Rebuild from bytes is **4.908747x** faster than reinserting points.
-- Rebuild from file is **4.290712x** faster than reinserting points.
-- Serialized blob size is **13,770,328 bytes**.
+- Rebuild from bytes is **12.497145x** faster than reinserting points.
+- Rebuild from file is **7.367322x** faster than reinserting points.
+- Serialized blob size is **18,104,173 bytes**.
 
 ----------------
 
 ## System Info
-- **OS**: CachyOS 6.18.5-2-cachyos x86_64
-- **Python**: CPython 3.14.2
+- **OS**: CachyOS 7.0.10-1-cachyos x86_64
+- **Python**: CPython 3.14.5
 - **CPU**: AMD Ryzen 7 3700X 8-Core Processor (16 threads)
 - **Memory**: 31.3 GB
 - **GPU**: NVIDIA GeForce RTX 5070 (11.9 GB)

fastquadtree-2.4.0/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.2.0 → fastquadtree-2.4.0}/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
-- 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 # 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.2.0 → fastquadtree-2.4.0}/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.2.0 → fastquadtree-2.4.0}/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.2.0 → fastquadtree-2.4.0}/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.2.0 → fastquadtree-2.4.0}/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",