fastquadtree 2.2.0__tar.gz → 2.3.0__tar.gz

{fastquadtree-2.2.0 → fastquadtree-2.3.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.3.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.3.0}/Cargo.toml

@@ -1,7 +1,8 @@
 [package]
 name = "fastquadtree"
-version = "2.2.0"
+version = "2.3.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.3.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.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastquadtree
-Version: 2.2.0
+Version: 2.3.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 for faster collision detection (depending on workload)
 - 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 replacement for `pygame.sprite.Group` with quadtree indexing for faster collision detection. |
 
 
 ## Quickstart
@@ -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.3.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 for faster collision detection (depending on workload)
 - 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 replacement for `pygame.sprite.Group` with quadtree indexing for faster collision detection. |
 
 
 ## Quickstart
@@ -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.3.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.2.0 → fastquadtree-2.3.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.2.0 → fastquadtree-2.3.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 for faster collision detection (depending on workload)
 - 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 replacement for pygame.sprite.Group with quadtree indexing (pygame install required)
 ```

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

@@ -8,7 +8,10 @@ from collections.abc import Sequence
 from typing import Any, Generic, TypeVar
 
 from ._common import (
+    FLAG_CORE_CODEC_WINCODE,
+    FLAG_MAX_DEPTH_PRESENT,
     SERIALIZATION_FORMAT_VERSION,
+    UNSUPPORTED_BINCODE_MESSAGE,
     Bounds,
     QuadTreeDType,
     SerializationError,
@@ -17,6 +20,7 @@ from ._common import (
     parse_container,
     validate_bounds,
     validate_np_dtype,
+    validate_preallocation_limit_bucket,
 )
 from ._insert_result import InsertResult
 
@@ -54,7 +58,13 @@ class _BaseQuadTree(Generic[G], ABC):
 
     @classmethod
     @abstractmethod
-    def _new_native_from_bytes(cls, data: bytes, dtype: QuadTreeDType) -> Any:
+    def _new_native_from_bytes(
+        cls,
+        data: bytes,
+        dtype: QuadTreeDType,
+        preallocation_limit_bytes: int | None = None,
+        disable_preallocation_limit: bool = False,
+    ) -> Any:
         """Create the native engine instance from serialized bytes."""
 
     # ---- Initialization ----
@@ -301,9 +311,9 @@ class _BaseQuadTree(Generic[G], ABC):
         """
         core_bytes = self._native.to_bytes()
 
-        flags = 0
+        flags = FLAG_CORE_CODEC_WINCODE
         if self._max_depth is not None:
-            flags |= 1  # max_depth_present
+            flags |= FLAG_MAX_DEPTH_PRESENT
 
         return build_container(
             fmt_ver=SERIALIZATION_FORMAT_VERSION,
@@ -319,16 +329,37 @@ class _BaseQuadTree(Generic[G], ABC):
         )
 
     @classmethod
-    def from_bytes(cls, data: bytes) -> _BaseQuadTree[G]:
+    def from_bytes(
+        cls,
+        data: bytes,
+        preallocation_limit_bytes: int | None = None,
+        disable_preallocation_limit: bool = False,
+    ) -> _BaseQuadTree[G]:
         """
         Deserialize a quadtree from bytes.
 
         Args:
             data: Bytes from to_bytes().
+            preallocation_limit_bytes: Optional native decode preallocation limit.
+                Must be one of the supported bucket values in bytes:
+                1024, 1048576, 4194304, 16777216, 67108864, 268435456, 1073741824.
+                If omitted, defaults to 67108864 bytes (64 MiB).
+            disable_preallocation_limit: Explicitly disable native preallocation
+                limits. Use only for trusted data.
 
         Returns:
             A new instance.
+
+        Raises:
+            SerializationError: If the container is malformed, the format version
+                is unsupported, or the payload uses legacy bincode encoding.
+            ValueError: If the requested preallocation bucket is invalid, or if
+                decoding would exceed the configured preallocation limit.
         """
+        validate_preallocation_limit_bucket(
+            preallocation_limit_bytes, disable_preallocation_limit
+        )
+
         parsed = parse_container(data)
 
         fmt_ver = parsed["fmt_ver"]
@@ -337,6 +368,8 @@ class _BaseQuadTree(Generic[G], ABC):
                 f"Unsupported serialization format version {fmt_ver}; "
                 f"this package supports up to {SERIALIZATION_FORMAT_VERSION}"
             )
+        if fmt_ver < 2 or not (parsed["flags"] & FLAG_CORE_CODEC_WINCODE):
+            raise SerializationError(UNSUPPORTED_BINCODE_MESSAGE)
 
         dtype = parsed["dtype"]
         core = parsed["core"]
@@ -348,6 +381,8 @@ class _BaseQuadTree(Generic[G], ABC):
         qt._max_depth = parsed["max_depth"]
         qt._next_id = parsed["next_id"]
         qt._count = parsed["count"]
-        qt._native = cls._new_native_from_bytes(core, dtype)
+        qt._native = cls._new_native_from_bytes(
+            core, dtype, preallocation_limit_bytes, disable_preallocation_limit
+        )
 
         return qt

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

@@ -9,9 +9,12 @@ from collections.abc import Sequence
 from typing import Any, Generic, TypeVar
 
 from ._common import (
+    FLAG_CORE_CODEC_WINCODE,
+    FLAG_MAX_DEPTH_PRESENT,
     SECTION_ITEMS,
     SECTION_OBJECTS,
     SERIALIZATION_FORMAT_VERSION,
+    UNSUPPORTED_BINCODE_MESSAGE,
     Bounds,
     Point,
     QuadTreeDType,
@@ -21,6 +24,7 @@ from ._common import (
     parse_container,
     validate_bounds,
     validate_np_dtype,
+    validate_preallocation_limit_bucket,
 )
 from ._insert_result import InsertResult
 from ._item import Item
@@ -210,7 +214,13 @@ class _BaseQuadTreeObjects(Generic[G, ItemType], ABC):
 
     @classmethod
     @abstractmethod
-    def _new_native_from_bytes(cls, data: bytes, dtype: QuadTreeDType) -> Any:
+    def _new_native_from_bytes(
+        cls,
+        data: bytes,
+        dtype: QuadTreeDType,
+        preallocation_limit_bytes: int | None = None,
+        disable_preallocation_limit: bool = False,
+    ) -> Any:
         """Create the native engine instance from serialized bytes."""
 
     @staticmethod
@@ -704,9 +714,9 @@ class _BaseQuadTreeObjects(Generic[G, ItemType], ABC):
         """
         core_bytes = self._native.to_bytes()
 
-        flags = 0
+        flags = FLAG_CORE_CODEC_WINCODE
         if self._max_depth is not None:
-            flags |= 1  # max_depth_present
+            flags |= FLAG_MAX_DEPTH_PRESENT
 
         # Always store items (id + geom) safely.
         items_payload = _encode_items_section(list(self._store.items()))
@@ -731,7 +741,11 @@ class _BaseQuadTreeObjects(Generic[G, ItemType], ABC):
 
     @classmethod
     def from_bytes(
-        cls, data: bytes, allow_objects: bool = False
+        cls,
+        data: bytes,
+        allow_objects: bool = False,
+        preallocation_limit_bytes: int | None = None,
+        disable_preallocation_limit: bool = False,
     ) -> _BaseQuadTreeObjects[G, ItemType]:
         """
         Deserialize a quadtree from bytes.
@@ -740,6 +754,12 @@ class _BaseQuadTreeObjects(Generic[G, ItemType], ABC):
             data: Bytes from to_bytes().
             allow_objects: If True, load pickled Python objects (unsafe).
                           If False (default), object payloads are silently ignored.
+            preallocation_limit_bytes: Optional native decode preallocation limit.
+                Must be one of the supported bucket values in bytes:
+                1024, 1048576, 4194304, 16777216, 67108864, 268435456, 1073741824.
+                If omitted, defaults to 67108864 bytes (64 MiB).
+            disable_preallocation_limit: Explicitly disable native preallocation
+                limits. Use only for trusted data.
 
         Returns:
             A new instance.
@@ -747,7 +767,17 @@ class _BaseQuadTreeObjects(Generic[G, ItemType], ABC):
         Note:
             Object deserialization uses pickle-like semantics. Never load
             serialized data from untrusted sources with allow_objects=True.
+
+        Raises:
+            SerializationError: If the container is malformed, the format version
+                is unsupported, or the payload uses legacy bincode encoding.
+            ValueError: If the requested preallocation bucket is invalid, or if
+                decoding would exceed the configured preallocation limit.
         """
+        validate_preallocation_limit_bucket(
+            preallocation_limit_bytes, disable_preallocation_limit
+        )
+
         parsed = parse_container(data)
 
         fmt_ver = parsed["fmt_ver"]
@@ -756,6 +786,8 @@ class _BaseQuadTreeObjects(Generic[G, ItemType], ABC):
                 f"Unsupported serialization format version {fmt_ver}; "
                 f"this package supports up to {SERIALIZATION_FORMAT_VERSION}"
             )
+        if fmt_ver < 2 or not (parsed["flags"] & FLAG_CORE_CODEC_WINCODE):
+            raise SerializationError(UNSUPPORTED_BINCODE_MESSAGE)
 
         dtype = parsed["dtype"]
         core = parsed["core"]
@@ -790,7 +822,9 @@ class _BaseQuadTreeObjects(Generic[G, ItemType], ABC):
         qt._capacity = parsed["capacity"]
         qt._max_depth = parsed["max_depth"]
         qt._count = parsed["count"]
-        qt._native = cls._new_native_from_bytes(core, dtype)
+        qt._native = cls._new_native_from_bytes(
+            core, dtype, preallocation_limit_bytes, disable_preallocation_limit
+        )
 
         # Rebuild store from decoded ids/geoms (+ optional objects)
         store: ObjStore[ItemType] = ObjStore()

{fastquadtree-2.2.0 → fastquadtree-2.3.0}/pysrc/fastquadtree/_common.py

@@ -5,13 +5,27 @@ from __future__ import annotations
 import math
 from typing import Any, Final, Literal, Union, overload
 
-SERIALIZATION_FORMAT_VERSION: Final[int] = 1
+SERIALIZATION_FORMAT_VERSION: Final[int] = 2
 
 # Serialization container constants (shared by Objects and non-Objects trees)
 SERIALIZATION_MAGIC: Final[bytes] = b"FQT0"  # fastquadtree container v0
 SERIALIZATION_ENDIANNESS: Final[str] = "<"  # little-endian
+FLAG_MAX_DEPTH_PRESENT: Final[int] = 1
+FLAG_CORE_CODEC_WINCODE: Final[int] = 1 << 1
+UNSUPPORTED_BINCODE_MESSAGE: Final[str] = (
+    "bincode serialization from fastquadtree v2.2 and earlier is no longer supported"
+)
 SECTION_ITEMS: int = 1  # safe: ids + geometry only
 SECTION_OBJECTS: int = 2  # unsafe: pickle payload (opt-in)
+NATIVE_PREALLOCATION_LIMIT_BUCKETS: Final[tuple[int, ...]] = (
+    1024,
+    1024 * 1024,
+    4 * 1024 * 1024,
+    16 * 1024 * 1024,
+    64 * 1024 * 1024,
+    256 * 1024 * 1024,
+    1024 * 1024 * 1024,
+)
 
 # Type aliases
 Bounds = tuple[
@@ -132,6 +146,30 @@ def validate_np_dtype(geoms: Any, expected_dtype: QuadTreeDType) -> None:
         )
 
 
+def validate_preallocation_limit_bucket(
+    preallocation_limit_bytes: int | None, disable_preallocation_limit: bool
+) -> None:
+    """
+    Validate that runtime native decode preallocation limits use a supported bucket.
+
+    Args:
+        preallocation_limit_bytes: Optional requested preallocation limit.
+        disable_preallocation_limit: If True, limit validation is skipped.
+
+    Raises:
+        ValueError: If preallocation_limit_bytes is not a supported bucket value.
+    """
+    if disable_preallocation_limit or preallocation_limit_bytes is None:
+        return
+
+    if preallocation_limit_bytes not in NATIVE_PREALLOCATION_LIMIT_BUCKETS:
+        buckets = ", ".join(str(v) for v in NATIVE_PREALLOCATION_LIMIT_BUCKETS)
+        raise ValueError(
+            "preallocation_limit_bytes must be one of the supported buckets "
+            f"(bytes): {buckets}"
+        )
+
+
 # ---------------------------
 # Serialization helpers
 # ---------------------------
@@ -323,7 +361,7 @@ def build_container(
     )
 
     md_bytes = b""
-    if flags & 1:
+    if flags & FLAG_MAX_DEPTH_PRESENT:
         if max_depth is None:
             raise SerializationError("max_depth flag set but max_depth is None")
         if int(max_depth) < 0:
@@ -415,7 +453,7 @@ def parse_container(data: bytes) -> dict[str, Any]:
     dtype = code_to_dtype(int(dtype_code))
 
     max_depth = None
-    if flags & 1:
+    if flags & FLAG_MAX_DEPTH_PRESENT:
         if len(buf) < off + 4:
             raise SerializationError("Data too short while reading max_depth")
         (md,) = struct.unpack_from(f"{SERIALIZATION_ENDIANNESS}i", buf, off)