fastquadtree 1.1.2__cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl → 1.2.1__cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

fastquadtree/_base_quadtree.py

@@ -1,6 +1,7 @@
 # _abc_quadtree.py
 from __future__ import annotations
 
+import pickle
 from abc import ABC, abstractmethod
 from typing import (
     TYPE_CHECKING,
@@ -58,8 +59,9 @@ class _BaseQuadTree(Generic[G, HitT, ItemType], ABC):
     def _new_native(self, bounds: Bounds, capacity: int, max_depth: int | None) -> Any:
         """Create the native engine instance."""
 
+    @staticmethod
     @abstractmethod
-    def _make_item(self, id_: int, geom: G, obj: Any | None) -> ItemType:
+    def _make_item(id_: int, geom: G, obj: Any | None) -> ItemType:
         """Build an ItemType from id, geometry, and optional object."""
 
     # ---- ctor ----
@@ -84,6 +86,91 @@ class _BaseQuadTree(Generic[G, HitT, ItemType], ABC):
         self._next_id = 0
         self._count = 0
 
+    # ---- serialization ----
+
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Serialize the quadtree to a dict suitable for JSON or other serialization.
+
+        Returns:
+            Includes a binary 'core' key for the native engine state, plus other metadata such as bounds and capacity and the obj store if tracking is enabled.
+
+        Example:
+            ```python
+            state = qt.to_dict()
+            assert "core" in state and "bounds" in state
+            ```
+        """
+
+        core_bytes = self._native.to_bytes()
+
+        return {
+            "core": core_bytes,
+            "store": self._store.to_dict() if self._store is not None else None,
+            "bounds": self._bounds,
+            "capacity": self._capacity,
+            "max_depth": self._max_depth,
+            "track_objects": self._track_objects,
+            "next_id": self._next_id,
+            "count": self._count,
+        }
+
+    def to_bytes(self) -> bytes:
+        """
+        Serialize the quadtree to bytes.
+
+        Returns:
+            Bytes representing the serialized quadtree. Can be saved as a file or loaded with `from_bytes()`.
+
+        Example:
+            ```python
+            blob = qt.to_bytes()
+            with open("tree.fqt", "wb") as f:
+                f.write(blob)
+            ```
+        """
+        return pickle.dumps(self.to_dict())
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> _BaseQuadTree[G, HitT, ItemType]:
+        """
+        Deserialize a quadtree from bytes.
+
+        Args:
+            data: Bytes representing the serialized quadtree from `to_bytes()`.
+
+        Returns:
+            A new quadtree instance with the same state as when serialized.
+
+        Example:
+            ```python
+            blob = qt.to_bytes()
+            qt2 = type(qt).from_bytes(blob)
+            assert qt2.count_items() == qt.count_items()
+            ```
+        """
+        in_dict = pickle.loads(data)
+        core_bytes = in_dict["core"]
+        store_dict = in_dict["store"]
+
+        qt = cls.__new__(cls)  # type: ignore[call-arg]
+        qt._native = cls._new_native_from_bytes(core_bytes)
+
+        if store_dict is not None:
+            qt._store = ObjStore.from_dict(store_dict, qt._make_item)
+        else:
+            qt._store = None
+
+        # Extract bounds, capacity, max_depth from native
+        qt._bounds = in_dict["bounds"]
+        qt._capacity = in_dict["capacity"]
+        qt._max_depth = in_dict["max_depth"]
+        qt._next_id = in_dict["next_id"]
+        qt._count = in_dict["count"]
+        qt._track_objects = in_dict["track_objects"]
+
+        return qt
+
     # ---- internal helper ----
 
     def _ids_to_objects(self, ids: Iterable[int]) -> list[Any]:
@@ -107,6 +194,13 @@ class _BaseQuadTree(Generic[G, HitT, ItemType], ABC):
 
         Raises:
             ValueError: If geometry is outside the tree bounds.
+
+        Example:
+            ```python
+            id0 = point_qt.insert((10.0, 20.0))  # for point trees
+            id1 = rect_qt.insert((0.0, 0.0, 5.0, 5.0), obj="box")  # for rect trees
+            assert isinstance(id0, int) and isinstance(id1, int)
+            ```
         """
         if self._store is not None:
             # Reuse a dense free slot if available, else append
@@ -152,6 +246,17 @@ class _BaseQuadTree(Generic[G, HitT, ItemType], ABC):
 
         Raises:
             ValueError: If any geometry is outside bounds.
+
+        Example:
+            ```python
+            n = qt.insert_many([(1.0, 1.0), (2.0, 2.0)])
+            assert n == 2
+
+            import numpy as np
+            arr = np.array([[3.0, 3.0], [4.0, 4.0]], dtype=np.float32)
+            n2 = qt.insert_many(arr)
+            assert n2 == 2
+            ```
         """
         if type(geoms) is list and len(geoms) == 0:
             return 0
@@ -216,8 +321,19 @@ class _BaseQuadTree(Generic[G, HitT, ItemType], ABC):
         """
         Delete an item by id and exact geometry.
 
+        Args:
+            id_: The id of the item to delete.
+            geom: The geometry of the item to delete.
+
         Returns:
             True if the item was found and deleted.
+
+        Example:
+            ```python
+            i = qt.insert((1.0, 2.0))
+            ok = qt.delete(i, (1.0, 2.0))
+            assert ok is True
+            ```
         """
         deleted = self._native.delete(id_, geom)
         if deleted:
@@ -230,6 +346,17 @@ class _BaseQuadTree(Generic[G, HitT, ItemType], ABC):
         """
         Attach or replace the Python object for an existing id.
         Tracking must be enabled.
+
+        Args:
+            id_: The id of the item to attach the object to.
+            obj: The Python object to attach.
+
+        Example:
+            ```python
+            i = qt.insert((2.0, 3.0), obj=None)
+            qt.attach(i, {"meta": 123})
+            assert qt.get(i) == {"meta": 123}
+            ```
         """
         if self._store is None:
             raise ValueError("Cannot attach objects when track_objects=False")
@@ -242,6 +369,16 @@ class _BaseQuadTree(Generic[G, HitT, ItemType], ABC):
     def delete_by_object(self, obj: Any) -> bool:
         """
         Delete an item by Python object identity. Tracking must be enabled.
+
+        Args:
+            obj: The Python object to delete.
+
+        Example:
+            ```python
+            i = qt.insert((3.0, 4.0), obj="tag")
+            ok = qt.delete_by_object("tag")
+            assert ok is True
+            ```
         """
         if self._store is None:
             raise ValueError("Cannot delete by object when track_objects=False")
@@ -256,6 +393,13 @@ class _BaseQuadTree(Generic[G, HitT, ItemType], ABC):
 
         If tracking is enabled, the id -> object mapping is also cleared.
         The ids are reset to start at zero again.
+
+        Example:
+            ```python
+            _ = qt.insert((5.0, 6.0))
+            qt.clear()
+            assert qt.count_items() == 0 and len(qt) == 0
+            ```
         """
         self._native = self._new_native(self._bounds, self._capacity, self._max_depth)
         self._count = 0
@@ -266,6 +410,14 @@ class _BaseQuadTree(Generic[G, HitT, ItemType], ABC):
     def get_all_objects(self) -> list[Any]:
         """
         Return all tracked Python objects in the tree.
+
+        Example:
+            ```python
+            _ = qt.insert((7.0, 8.0), obj="a")
+            _ = qt.insert((9.0, 1.0), obj="b")
+            objs = qt.get_all_objects()
+            assert set(objs) == {"a", "b"}
+            ```
         """
         if self._store is None:
             raise ValueError("Cannot get objects when track_objects=False")
@@ -274,6 +426,13 @@ class _BaseQuadTree(Generic[G, HitT, ItemType], ABC):
     def get_all_items(self) -> list[ItemType]:
         """
         Return all Item wrappers in the tree.
+
+         Example:
+            ```python
+            _ = qt.insert((1.0, 1.0), obj=None)
+            items = qt.get_all_items()
+            assert hasattr(items[0], "id_") and hasattr(items[0], "geom")
+            ```
         """
         if self._store is None:
             raise ValueError("Cannot get items when track_objects=False")
@@ -282,12 +441,25 @@ class _BaseQuadTree(Generic[G, HitT, ItemType], ABC):
     def get_all_node_boundaries(self) -> list[Bounds]:
         """
         Return all node boundaries in the tree. Useful for visualization.
+
+        Example:
+            ```python
+            bounds = qt.get_all_node_boundaries()
+            assert isinstance(bounds, list)
+            ```
         """
         return self._native.get_all_node_boundaries()
 
     def get(self, id_: int) -> Any | None:
         """
         Return the object associated with id, if tracking is enabled.
+
+        Example:
+            ```python
+            i = qt.insert((1.0, 2.0), obj={"k": "v"})
+            obj = qt.get(i)
+            assert obj == {"k": "v"}
+            ```
         """
         if self._store is None:
             raise ValueError("Cannot get objects when track_objects=False")
@@ -297,6 +469,13 @@ class _BaseQuadTree(Generic[G, HitT, ItemType], ABC):
     def count_items(self) -> int:
         """
         Return the number of items currently in the tree (native count).
+
+        Example:
+            ```python
+            before = qt.count_items()
+            _ = qt.insert((2.0, 2.0))
+            assert qt.count_items() == before + 1
+            ```
         """
         return self._native.count_items()
 

fastquadtree/_item.py

@@ -27,6 +27,35 @@ class Item:
         self.geom: Point | Bounds = geom
         self.obj: Any | None = obj
 
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Serialize the item to a dictionary.
+
+        Returns:
+            A dictionary with 'id', 'geom', and 'obj' keys.
+        """
+        return {
+            "id": self.id_,
+            "geom": self.geom,
+            "obj": self.obj,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Item:
+        """
+        Deserialize an item from a dictionary.
+
+        Args:
+            data: A dictionary with 'id', 'geom', and 'obj' keys.
+
+        Returns:
+            An Item instance populated with the deserialized data.
+        """
+        id_ = data["id"]
+        geom = data["geom"]
+        obj = data["obj"]
+        return cls(id_, geom, obj)
+
 
 class PointItem(Item):
     """

fastquadtree/_obj_store.py

@@ -35,11 +35,40 @@ class ObjStore(Generic[TItem]):
 
         if items:
             for it in items:
-                self.add(it)
+                self.add(it, handle_out_of_order=True)
+
+    # ---- Serialization ----
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Serialize to a dict suitable for JSON or other serialization.
+
+        Returns:
+            A dict with 'items' key containing list of serialized items.
+        """
+        items = [it.to_dict() for it in self._arr if it is not None]
+        return {"items": items}
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any], item_factory: Any) -> ObjStore[TItem]:
+        """
+        Deserialize from a dict.
+
+        Args:
+            data: A dict with 'items' key containing list of serialized items.
+            item_factory: A callable that takes (id, obj) and returns an Item.
+
+        Returns:
+            An ObjStore instance populated with the deserialized items.
+        """
+        items = []
+        for item_data in data.get("items", []):
+            item = Item.from_dict(item_data)
+            items.append(item_factory(item.id_, item.geom, item.obj))
+        return cls(items)
 
     # -------- core --------
 
-    def add(self, item: TItem) -> None:
+    def add(self, item: TItem, handle_out_of_order: bool = False) -> None:
         """
         Insert or replace the mapping at item.id_. Reverse map updated so obj points to id.
         """
@@ -48,9 +77,14 @@ class ObjStore(Generic[TItem]):
 
         # ids must be dense and assigned by the caller
         if id_ > len(self._arr):
-            raise AssertionError(
-                "ObjStore.add received an out-of-order id, use alloc_id() to get the next available id"
-            )
+            if not handle_out_of_order:
+                raise AssertionError(
+                    "ObjStore.add received an out-of-order id, use alloc_id() to get the next available id"
+                )
+            # fill holes with None
+            while len(self._arr) < id_:
+                self._arr.append(None)
+                self._objs.append(None)
 
         if id_ == len(self._arr):
             # append

fastquadtree/point_quadtree.py

@@ -49,6 +49,18 @@ class QuadTree(_BaseQuadTree[Point, _IdCoord, PointItem]):
             track_objects=track_objects,
         )
 
+    @classmethod
+    def from_bytes(cls, data: bytes) -> QuadTree:
+        """
+        Create a QuadTree instance from serialized bytes.
+
+        Args:
+            data: Serialized byte data from `to_bytes()`.
+        Returns:
+            A QuadTree instance.
+        """
+        return super().from_bytes(data)
+
     @overload
     def query(
         self, rect: Bounds, *, as_items: Literal[False] = ...
@@ -68,6 +80,13 @@ class QuadTree(_BaseQuadTree[Point, _IdCoord, PointItem]):
         Returns:
             If as_items is False: list of (id, x, y) tuples.
             If as_items is True: list of Item objects.
+
+        Example:
+            ```python
+            results = qt.query((10.0, 10.0, 20.0, 20.0), as_items=True)
+            for item in results:
+                print(f"Found point id={item.id_} at {item.geom} with obj={item.obj}")
+            ```
         """
         if not as_items:
             return self._native.query(rect)
@@ -145,5 +164,11 @@ class QuadTree(_BaseQuadTree[Point, _IdCoord, PointItem]):
             return _RustQuadTree(bounds, capacity)
         return _RustQuadTree(bounds, capacity, max_depth=max_depth)
 
-    def _make_item(self, id_: int, geom: Point, obj: Any | None) -> PointItem:
+    @classmethod
+    def _new_native_from_bytes(cls, data: bytes) -> Any:
+        """Create a new native engine instance from serialized bytes."""
+        return _RustQuadTree.from_bytes(data)
+
+    @staticmethod
+    def _make_item(id_: int, geom: Point, obj: Any | None) -> PointItem:
         return PointItem(id_, geom, obj)

fastquadtree/rect_quadtree.py

@@ -50,6 +50,18 @@ class RectQuadTree(_BaseQuadTree[Bounds, _IdRect, RectItem]):
             track_objects=track_objects,
         )
 
+    @classmethod
+    def from_bytes(cls, data: bytes) -> RectQuadTree:
+        """
+        Create a RectQuadTree instance from serialized bytes.
+
+        Args:
+            data: Serialized byte data from `to_bytes()`.
+        Returns:
+            A RectQuadTree instance.
+        """
+        return super().from_bytes(data)
+
     @overload
     def query(
         self, rect: Bounds, *, as_items: Literal[False] = ...
@@ -69,6 +81,13 @@ class RectQuadTree(_BaseQuadTree[Bounds, _IdRect, RectItem]):
         Returns:
             If as_items is False: list of (id, x0, y0, x1, y1) tuples.
             If as_items is True: list of Item objects.
+
+        Example:
+            ```python
+            results = rqt.query((10.0, 10.0, 20.0, 20.0), as_items=True)
+            for item in results:
+                print(f"Found rect id={item.id_} at {item.geom} with obj={item.obj}")
+            ```
         """
         if not as_items:
             return self._native.query(rect)
@@ -81,5 +100,11 @@ class RectQuadTree(_BaseQuadTree[Bounds, _IdRect, RectItem]):
             return _RustRectQuadTree(bounds, capacity)
         return _RustRectQuadTree(bounds, capacity, max_depth=max_depth)
 
-    def _make_item(self, id_: int, geom: Bounds, obj: Any | None) -> RectItem:
+    @classmethod
+    def _new_native_from_bytes(cls, data: bytes) -> Any:
+        """Create a new native engine instance from serialized bytes."""
+        return _RustRectQuadTree.from_bytes(data)
+
+    @staticmethod
+    def _make_item(id_: int, geom: Bounds, obj: Any | None) -> RectItem:
         return RectItem(id_, geom, obj)

{fastquadtree-1.1.2.dist-info → fastquadtree-1.2.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastquadtree
-Version: 1.1.2
+Version: 1.2.1
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Rust
@@ -70,6 +70,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
+- Fast [serialization](https://elan456.github.io/fastquadtree/benchmark/#serialization-vs-rebuild) to/from bytes
 - [100% test coverage](https://codecov.io/gh/Elan456/fastquadtree) and CI on GitHub Actions
 - Offers a drop-in [pyqtree shim](https://elan456.github.io/fastquadtree/benchmark/#pyqtree-drop-in-shim-performance-gains) that is 6.567x faster while keeping the same API
 

fastquadtree-1.2.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+fastquadtree-1.2.1.dist-info/METADATA,sha256=IYzvJNOV07j4qtOFQqryt15YjrnuWrSjJpK0NUDe-1E,9614
+fastquadtree-1.2.1.dist-info/WHEEL,sha256=cqfH6P_NujaeOc1olR46J5a7YgoxWJnrr5iZ1_DMqps,129
+fastquadtree-1.2.1.dist-info/licenses/LICENSE,sha256=pRuvcuqIMtEUBMgvP1Bc4fOHydzeuA61c6DQoQ1pb1w,1071
+fastquadtree/__init__.py,sha256=rtkveNz7rScRasTRGu1yEqzeoJfLfreJNxg21orPL-U,195
+fastquadtree/_base_quadtree.py,sha256=NhUkMulVa2ItCtx5rEnE_asHY3aGN0XxG6m-AYJk7CE,15091
+fastquadtree/_item.py,sha256=EDS3nJHdVtjDsuTqTZKGTZH8iWJIQ-TKxLXqvMScNPA,2405
+fastquadtree/_native.abi3.so,sha256=KowjAh4FNt39FRoddwNjgcSWSG1tGRV7McT8WWRO8aE,540600
+fastquadtree/_obj_store.py,sha256=HeYFGUPYhvxBzL7Js0g0jsIxflpZS6RsXNk50rGeNlA,6522
+fastquadtree/point_quadtree.py,sha256=BM6mxw2pSmAKkOgXnosREfC6WOXCgEYNeQDlvnlEbKQ,5945
+fastquadtree/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fastquadtree/pyqtree.py,sha256=2Khh1gCPalD4z0gb3EmqtzMoga08E9BkB0j5bwkiRPU,6076
+fastquadtree/rect_quadtree.py,sha256=82IygiEmJ4JdA6LBDXq288cs9VfS3LpdJdkjCPcYCKM,3807
+fastquadtree-1.2.1.dist-info/RECORD,,

fastquadtree-1.1.2.dist-info/RECORD

@@ -1,13 +0,0 @@
-fastquadtree-1.1.2.dist-info/METADATA,sha256=Xuiwr9cpXZhCSt6P3e_kr6t4YWHD0PTszufwxLgmq74,9501
-fastquadtree-1.1.2.dist-info/WHEEL,sha256=cqfH6P_NujaeOc1olR46J5a7YgoxWJnrr5iZ1_DMqps,129
-fastquadtree-1.1.2.dist-info/licenses/LICENSE,sha256=pRuvcuqIMtEUBMgvP1Bc4fOHydzeuA61c6DQoQ1pb1w,1071
-fastquadtree/__init__.py,sha256=rtkveNz7rScRasTRGu1yEqzeoJfLfreJNxg21orPL-U,195
-fastquadtree/_base_quadtree.py,sha256=o5T0xqDM9i_JjpYF4U7VmLM0qUHkw0wr0bbRqb-CGt4,9901
-fastquadtree/_item.py,sha256=LoTDr7zlsZyUrrKK6Ketzl5fxTcFF8YbcxEXbQ65st4,1679
-fastquadtree/_native.abi3.so,sha256=C8MsshF2fjlaMGhJP6IkoP0D-7MFE6A1gKE6BkZttVE,508576
-fastquadtree/_obj_store.py,sha256=vmhZGdzEoTQHvRbFjTne_0X2Z1l48SXyB6I9SAjjbiM,5267
-fastquadtree/point_quadtree.py,sha256=Pz8ZS7N3kYSYJJYGa3ghKzy7d3JCA1dbi9nfEwwpF_k,5178
-fastquadtree/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-fastquadtree/pyqtree.py,sha256=2Khh1gCPalD4z0gb3EmqtzMoga08E9BkB0j5bwkiRPU,6076
-fastquadtree/rect_quadtree.py,sha256=7F-JceCHn5RLhztxSYCIJEZ_e2TV-NeobobbrdauJQA,3024
-fastquadtree-1.1.2.dist-info/RECORD,,