fastquadtree 1.2.0__tar.gz → 1.2.3__tar.gz

{fastquadtree-1.2.0 → fastquadtree-1.2.3}/.github/workflows/release.yml

@@ -16,7 +16,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: "3.10"
+          python-version: "3.9"
 
       - name: Create venv for maturin develop
         run: python -m venv .venv

{fastquadtree-1.2.0 → fastquadtree-1.2.3}/Cargo.lock

@@ -30,7 +30,7 @@ dependencies = [
 
 [[package]]
 name = "fastquadtree"
-version = "1.2.0"
+version = "1.2.3"
 dependencies = [
  "bincode",
  "numpy",

{fastquadtree-1.2.0 → fastquadtree-1.2.3}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "fastquadtree"
-version = "1.2.0"
+version = "1.2.3"
 edition = "2021"
 readme = "README.md"
 

{fastquadtree-1.2.0 → fastquadtree-1.2.3}/PKG-INFO

@@ -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.0 → fastquadtree-1.2.3}/README.md

@@ -5,6 +5,8 @@
 
 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)
@@ -24,7 +26,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
@@ -36,7 +38,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.0 → fastquadtree-1.2.3}/docs/future_features.md

@@ -5,26 +5,42 @@ If you really want any of these features, please let us know by opening an issue
 
 If you have any suggestions or would like to contribute, please feel free to open an issue or a pull request.
 
-## Planned Features
+The features will likely be implemented in the order they are listed below, but this is not guaranteed.
 
-### 1. [COMPLETE] Quadtree serialization
+## 🚧 Planned Features
 
-By serializing the quadtree, we can save its state to a file and load it later. This will allow us to persist the quadtree structure and data across sessions. For example, you could pre build a quadtree with all the walls in your video game level, serialize it to a file, and then load it when the game starts. This will heavily reduce the game load time since you won't have to rebuild the quadtree from scratch every time.
+### 1. Configurable Quadtree Coordinate Type
 
-### 2. Circle support
+Currently, the point quadtree only uses f32 for point coordinates, limiting precision in favor of better performance.
+To make the quadtree more flexible, we could allow users to specify the coordinate type (e.g., f64, i32, etc.) when creating a quadtree.
+The f32 will remain the default, but users will be able to specify a different type if needed.
 
-Currently, we support points and rectangles in two separate quadtrees.
-For example, in the ball-pit demo, we use a point quadtree, but then query a larger area to account for the radius of the balls.
-With a circle quadtree, we could directly insert circles and perform circle-circle collision detection.
+If the type cannot be made truly generic, then only the following types would be supported: f32, f64, i32, i64
 
-### 3. KNN with criteria function
+### 2. KNN with criteria function
 
 Currently, KNN only supports finding the nearest neighbors based on euclidean distance.
 By adding a criteria function, we could allow users to define custom criteria for finding neighbors by passing a function that 
 takes in a point and returns a score. The KNN algorithm would then use this score to determine the nearest neighbors.
 
-### 4. KNN in rectangle quadtree
+### 3. KNN in rectangle quadtree
 
 Currently, KNN is only supported in the point quadtree. By adding KNN support to the rectangle quadtree, we could allow users to find the nearest rectangles to a given point. This would be to the nearest edge of the rectangle, adding complexity to the algorithm.
 However, it will allow for really quick collision detection between a point and a set of rectangles as the point can just do
-robust-collision handling with the nearest rectangles.
+robust-collision handling with the nearest rectangles.
+
+### 4. Circle support
+
+Currently, we support points and rectangles in two separate quadtrees.
+For example, in the ball-pit demo, we use a point quadtree, but then query a larger area to account for the radius of the balls.
+With a circle quadtree, we could directly insert circles and perform circle-circle collision detection.
+
+A good alternative is to use the rectangle quadtree and insert the minimum bounding rectangles of the circles.
+
+## ✅ Completed Planned Features
+
+Once a feature from above is completed, it will be moved to this section.
+
+### Quadtree serialization
+
+By serializing the quadtree, we can save its state to a file and load it later. This will allow us to persist the quadtree structure and data across sessions. For example, you could pre build a quadtree with all the walls in your video game level, serialize it to a file, and then load it when the game starts. This will heavily reduce the game load time since you won't have to rebuild the quadtree from scratch every time.

{fastquadtree-1.2.0 → fastquadtree-1.2.3}/mkdocs.yml

@@ -12,10 +12,12 @@ theme:
     - navigation.tracking
     - navigation.indexes
     - content.code.copy
-    - toc.integrate
+    - toc.follow
     - search.suggest
     - search.highlight
     - content.tooltips
+    - navigation.footer
+    - navigation.top
   palette:
     - scheme: slate
       primary: indigo
@@ -37,13 +39,14 @@ plugins:
           options:
             docstring_style: google
             merge_init_into_class: true
-            show_source: true
+            show_source: false
             show_root_heading: false
             show_signature: true
             show_if_no_docstring: true
-            separate_signature: true
-            line_length: 88
-            heading_level: 2
+            separate_signature: false
+            line_length: 100
+            heading_level: 3
+            members_order: source
             filters:  # Exclude __slots__ and __len__ and anything with a single underscore prefix (don't filter insert_many even though it has a single underscore)
               - "!__slots__"
               - "!__len__"

{fastquadtree-1.2.0 → fastquadtree-1.2.3}/pyproject.toml

@@ -8,7 +8,7 @@ name = "fastquadtree"
 dynamic = ["version"]
 description = "Rust-accelerated quadtree for Python with fast inserts, range queries, and k-NN search."
 readme = { file = "README.md", content-type = "text/markdown" }
-requires-python = ">=3.8"
+requires-python = ">=3.9"
 dependencies = [] # No runtime dependencies
 license = { file = "LICENSE" }
 authors = [{ name = "Ethan Anderson" }]

{fastquadtree-1.2.0 → fastquadtree-1.2.3}/pysrc/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-1.2.0 → fastquadtree-1.2.3}/pysrc/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-1.2.0 → fastquadtree-1.2.3}/pysrc/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)