fastquadtree 1.2.0__cp38-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl → 1.2.3__cp38-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl

fastquadtree/_base_quadtree.py

@@ -18,6 +18,8 @@ from ._item import Item  # base class for PointItem and RectItem
 from ._obj_store import ObjStore
 
 if TYPE_CHECKING:
+    from typing import Self  # Only in Python 3.11+
+
     from numpy.typing import NDArray
 
 Bounds = Tuple[float, float, float, float]
@@ -59,6 +61,10 @@ 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."""
 
+    @classmethod
+    def _new_native_from_bytes(cls, data: bytes) -> Any:
+        """Create the native engine instance from serialized bytes."""
+
     @staticmethod
     @abstractmethod
     def _make_item(id_: int, geom: G, obj: Any | None) -> ItemType:
@@ -94,6 +100,12 @@ class _BaseQuadTree(Generic[G, HitT, ItemType], ABC):
 
         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()
@@ -115,11 +127,18 @@ class _BaseQuadTree(Generic[G, HitT, ItemType], ABC):
 
         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]:
+    def from_bytes(cls, data: bytes) -> Self:
         """
         Deserialize a quadtree from bytes.
 
@@ -128,6 +147,13 @@ class _BaseQuadTree(Generic[G, HitT, ItemType], ABC):
 
         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"]
@@ -174,6 +200,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
@@ -219,6 +252,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
@@ -283,8 +327,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:
@@ -297,6 +352,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")
@@ -309,6 +375,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")
@@ -323,6 +399,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
@@ -333,6 +416,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")
@@ -341,6 +432,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")
@@ -349,12 +447,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")
@@ -364,6 +475,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/point_quadtree.py

@@ -49,18 +49,6 @@ 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] = ...
@@ -80,6 +68,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)

fastquadtree/rect_quadtree.py

@@ -50,18 +50,6 @@ 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] = ...
@@ -81,6 +69,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)

{fastquadtree-1.2.0.dist-info → fastquadtree-1.2.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastquadtree
-Version: 1.2.0
+Version: 1.2.3
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Rust
@@ -31,7 +31,7 @@ License-File: LICENSE
 Summary: Rust-accelerated quadtree for Python with fast inserts, range queries, and k-NN search.
 Keywords: quadtree,spatial-index,geometry,rust,pyo3,nearest-neighbor,k-nn
 Author: Ethan Anderson
-Requires-Python: >=3.8
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 Project-URL: Homepage, https://github.com/Elan456/fastquadtree
 Project-URL: Repository, https://github.com/Elan456/fastquadtree
@@ -45,6 +45,8 @@ Project-URL: Issues, https://github.com/Elan456/fastquadtree/issues
 
 Rust-optimized quadtree with a clean Python API
 
+👉 **Check out the Docs:** https://elan456.github.io/fastquadtree/
+
 [![PyPI](https://img.shields.io/pypi/v/fastquadtree.svg)](https://pypi.org/project/fastquadtree/)
 [![Python versions](https://img.shields.io/pypi/pyversions/fastquadtree.svg)](https://pypi.org/project/fastquadtree/)
 [![Downloads](https://static.pepy.tech/personalized-badge/fastquadtree?period=total&units=INTERNATIONAL_SYSTEM&left_color=GRAY&right_color=BLUE&left_text=Total%20Downloads)](https://pepy.tech/projects/fastquadtree)
@@ -64,7 +66,7 @@ Rust-optimized quadtree with a clean Python API
 
 ## Why use fastquadtree
 
-- Clean [Python API](https://elan456.github.io/fastquadtree/api/quadtree/) with no external dependencies and modern typing hints
+- Clean [Python API](https://elan456.github.io/fastquadtree/api/quadtree/) with **no external dependencies** and modern typing hints
 - The fastest quadtree Python package ([>10x faster](https://elan456.github.io/fastquadtree/benchmark/) than pyqtree)
 - Prebuilt wheels for Windows, macOS, and Linux
 - Support for [inserting bounding boxes](https://elan456.github.io/fastquadtree/api/rect_quadtree/) or points
@@ -76,7 +78,6 @@ Rust-optimized quadtree with a clean Python API
 
 ----
 
-👉 **Docs:** https://elan456.github.io/fastquadtree/
 
 ## Examples
 See examples of how fastquadtree can be used in the [runnables](https://elan456.github.io/fastquadtree/runnables/) section.

fastquadtree-1.2.3.dist-info/RECORD

@@ -0,0 +1,13 @@
+fastquadtree-1.2.3.dist-info/METADATA,sha256=e0f4sEJZ-BgTh9khREHE9BtckrlT0k1fMg2JvW5NWis,9633
+fastquadtree-1.2.3.dist-info/WHEEL,sha256=xBqaWU3Z-cfW-EFy0ENuEqxgXZXkIHUBkA1cT6FlqGM,127
+fastquadtree-1.2.3.dist-info/licenses/LICENSE,sha256=pRuvcuqIMtEUBMgvP1Bc4fOHydzeuA61c6DQoQ1pb1w,1071
+fastquadtree/__init__.py,sha256=rtkveNz7rScRasTRGu1yEqzeoJfLfreJNxg21orPL-U,195
+fastquadtree/_base_quadtree.py,sha256=-umYxuVnKXd7jXcCU2VU2E55kdfUraVrhoN2lpbPQFI,15262
+fastquadtree/_item.py,sha256=EDS3nJHdVtjDsuTqTZKGTZH8iWJIQ-TKxLXqvMScNPA,2405
+fastquadtree/_native.abi3.so,sha256=L7seTFIykBK3bRbAFkQ767e6_12F99SdK3dgxBeUQv0,556588
+fastquadtree/_obj_store.py,sha256=HeYFGUPYhvxBzL7Js0g0jsIxflpZS6RsXNk50rGeNlA,6522
+fastquadtree/point_quadtree.py,sha256=AQKZaO14wrf2PX9QLV_mAC5EjqSOQ_csmzeKAK4fZHw,5632
+fastquadtree/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fastquadtree/pyqtree.py,sha256=2Khh1gCPalD4z0gb3EmqtzMoga08E9BkB0j5bwkiRPU,6076
+fastquadtree/rect_quadtree.py,sha256=JN72J8kXasl9JHL3qgiDUBNRL2H-TnkB_mgRIUYzyfE,3482
+fastquadtree-1.2.3.dist-info/RECORD,,

fastquadtree-1.2.0.dist-info/RECORD

@@ -1,13 +0,0 @@
-fastquadtree-1.2.0.dist-info/METADATA,sha256=MUUv_93xtLD1Vbsm3t0JelXhuKt0VP1OmFlkQPcioHU,9614
-fastquadtree-1.2.0.dist-info/WHEEL,sha256=xBqaWU3Z-cfW-EFy0ENuEqxgXZXkIHUBkA1cT6FlqGM,127
-fastquadtree-1.2.0.dist-info/licenses/LICENSE,sha256=pRuvcuqIMtEUBMgvP1Bc4fOHydzeuA61c6DQoQ1pb1w,1071
-fastquadtree/__init__.py,sha256=rtkveNz7rScRasTRGu1yEqzeoJfLfreJNxg21orPL-U,195
-fastquadtree/_base_quadtree.py,sha256=ukiCKjsOPmnrkkKNLNJS5ad0X2HURYAWp9W60pk-c9Q,12045
-fastquadtree/_item.py,sha256=EDS3nJHdVtjDsuTqTZKGTZH8iWJIQ-TKxLXqvMScNPA,2405
-fastquadtree/_native.abi3.so,sha256=CVib-xgwo5sbXSJ5ypr25JmZ8u3reVrnivgamFeN-eM,556572
-fastquadtree/_obj_store.py,sha256=HeYFGUPYhvxBzL7Js0g0jsIxflpZS6RsXNk50rGeNlA,6522
-fastquadtree/point_quadtree.py,sha256=5ic-ZPq2AC20f9GkunKQAoH-W_doRFePOlJwqhST0FI,5697
-fastquadtree/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-fastquadtree/pyqtree.py,sha256=2Khh1gCPalD4z0gb3EmqtzMoga08E9BkB0j5bwkiRPU,6076
-fastquadtree/rect_quadtree.py,sha256=9JXqvh9WZGy7ZcfbXIRCWUf8oYpQz2QLB39f6XdP7u8,3559
-fastquadtree-1.2.0.dist-info/RECORD,,