docs: overhaul pyqtree docstrings + add loose type annotations

Author: Elan456

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "fastquadtree"
-version = "1.3.1"
+version = "1.3.2"
 edition = "2021"
 
 [lib]

Cargo.toml

@@ -1,4 +1,4 @@
-# fastquadtree.pyqtree
+# fastquadtree.pyqtree.Index
 ::: fastquadtree.pyqtree.Index
     options:
         inherited_members: true

docs/api/pyqtree.md

@@ -5,8 +5,9 @@
 
 from __future__ import annotations
 
+from collections.abc import Iterable
 from operator import itemgetter
-from typing import Any, Tuple
+from typing import Any, SupportsFloat, Tuple
 
 from ._native import RectQuadTree
 
@@ -34,18 +35,18 @@ def gather_objs(objs, ids, chunk=2048):
 
 class Index:
     """
-    The class below is taken from the pyqtree package, but the implementation
+    The interface of the class below is taken from the pyqtree package, but the implementation
     has been modified to use the fastquadtree package as a backend instead of
     the original pure-python implementation.
     Based on the benchmarks, this gives a overall performance boost of 6.514x.
     See the benchmark section of the docs for more details and the latest numbers.
 
-    Original docstring from pyqtree follows:
-    The top spatial index to be created by the user. Once created it can be
-    populated with geographically placed members that can later be tested for
-    intersection with a user inputted geographic bounding box. Note that the
-    index can be iterated through in a for-statement, which loops through all
-    all the quad instances and lets you access their properties.
+    Index is  the top-level class for creating and using a quadtree spatial index
+    with the original pyqtree interface. If you are not migrating from pyqtree,
+    consider using the RectQuadTree class for detailed control and better performance.
+
+    This class wraps a RectQuadTree instance and provides methods to insert items with bounding boxes,
+    remove items, and query for items intersecting a given bounding box.
 
     Example usage:
     ```python
@@ -65,32 +66,36 @@ class Index:
 
     def __init__(
         self,
-        bbox=None,
-        x=None,
-        y=None,
-        width=None,
-        height=None,
-        max_items=MAX_ITEMS,
-        max_depth=MAX_DEPTH,
+        bbox: Iterable[SupportsFloat] | None = None,
+        x: float | int | None = None,
+        y: float | int | None = None,
+        width: float | int | None = None,
+        height: float | int | None = None,
+        max_items: int = MAX_ITEMS,
+        max_depth: int = MAX_DEPTH,
     ):
         """
         Initiate by specifying either 1) a bbox to keep track of, or 2) with an xy centerpoint and a width and height.
 
-        Parameters:
-        - **bbox**: The coordinate system bounding box of the area that the quadtree should
+        Args:
+          bbox: The coordinate system bounding box of the area that the quadtree should
             keep track of, as a 4-length sequence (xmin,ymin,xmax,ymax)
-        - **x**:
+          x:
             The x center coordinate of the area that the quadtree should keep track of.
-        - **y**
+          y:
             The y center coordinate of the area that the quadtree should keep track of.
-        - **width**:
+          width:
             How far from the xcenter that the quadtree should look when keeping track.
-        - **height**:
+          height:
             How far from the ycenter that the quadtree should look when keeping track
-        - **max_items** (optional): The maximum number of items allowed per quad before splitting
-            up into four new subquads. Default is 10.
-        - **max_depth** (optional): The maximum levels of nested subquads, after which no more splitting
+          max_items (optional): The maximum number of items allowed per quad before splitting
+              up into four new subquads. Default is 10.
+          max_depth (optional): The maximum levels of nested subquads, after which no more splitting
             occurs and the bottommost quad nodes may grow indefinately. Default is 20.
+
+        Note:
+            Either the bbox argument must be set, or the x, y, width, and height
+            arguments must be set.
         """
         if bbox is not None:
             x1, y1, x2, y2 = bbox
@@ -114,15 +119,15 @@ def __init__(
         self._free = []
         self._item_to_id = {}
 
-    def insert(self, item: Any, bbox):  # pyright: ignore[reportIncompatibleMethodOverride]
+    def insert(self, item: Any, bbox: Iterable[SupportsFloat]):
         """
         Inserts an item into the quadtree along with its bounding box.
 
-        Parameters:
-        - **item**: The item to insert into the index, which will be returned by the intersection method
-        - **bbox**: The spatial bounding box tuple of the item, with four members (xmin,ymin,xmax,ymax)
+        Args:
+          item: The item to insert into the index, which will be returned by the intersection method
+          bbox: The spatial bounding box tuple of the item, with four members (xmin,ymin,xmax,ymax)
         """
-        if type(bbox) is list:  # Handle list input
+        if type(bbox) is not tuple:  # Handle non-tuple input
             bbox = tuple(bbox)
 
         if self._free:
@@ -134,36 +139,37 @@ def insert(self, item: Any, bbox):  # pyright: ignore[reportIncompatibleMethodOv
         self._qt.insert(rid, bbox)
         self._item_to_id[id(item)] = rid
 
-    def remove(self, item, bbox):
+    def remove(self, item: Any, bbox: Iterable[SupportsFloat]):
         """
         Removes an item from the quadtree.
 
-        Parameters:
-        - **item**: The item to remove from the index
-        - **bbox**: The spatial bounding box tuple of the item, with four members (xmin,ymin,xmax,ymax)
+        Args:
+          item: The item to remove from the index
+          bbox: The spatial bounding box tuple of the item, with four members (xmin,ymin,xmax,ymax)
 
-        Both parameters need to exactly match the parameters provided to the insert method.
+        Note:
+            Both parameters need to exactly match the parameters provided to the insert method.
         """
-        if type(bbox) is list:  # Handle list input
+        if type(bbox) is not tuple:  # Handle non-tuple input
             bbox = tuple(bbox)
 
         rid = self._item_to_id.pop(id(item))
         self._qt.delete(rid, bbox)
         self._objects[rid] = None
         self._free.append(rid)
 
-    def intersect(self, bbox):
+    def intersect(self, bbox: Iterable[SupportsFloat]) -> list:
         """
-        Intersects an input boundingbox rectangle with all of the items
+        Intersects an input bounding box rectangle with all of the items
         contained in the quadtree.
 
-        Parameters:
-        - **bbox**: A spatial bounding box tuple with four members (xmin,ymin,xmax,ymax)
+        Args:
+          bbox: A spatial bounding box tuple with four members (xmin,ymin,xmax,ymax)
 
         Returns:
-        - A list of inserted items whose bounding boxes intersect with the input bbox.
+          A list of inserted items whose bounding boxes intersect with the input bbox.
         """
-        if type(bbox) is list:  # Handle list input
+        if type(bbox) is not tuple:  # Handle non-tuple input
             bbox = tuple(bbox)
         result = self._qt.query_ids(bbox)
         # result = [id1, id2, ...]

pysrc/fastquadtree/pyqtree.py

@@ -401,3 +401,73 @@ def test_insert_list_and_tuple_equivalence():
     # Both objects should be present
     results = idx.intersect((0.0, 0.0, 100.0, 100.0))
     assert set(results) == {obj1, obj2}
+
+
+def test_insert_non_list_non_tuple_iterator():
+    """Test that any iterable (not just list/tuple) works for bbox in insert."""
+    idx = FQTIndex(bbox=WORLD)
+
+    obj1, box1 = "obj1", (10.0, 10.0, 20.0, 20.0)
+
+    obj2 = "obj2"
+
+    def obj2_box2_iterator():
+        yield 30.0
+        yield 30.0
+        yield 40.0
+        yield 40.0
+
+    # Insert using tuple
+    idx.insert(obj1, box1)
+
+    # Insert using range iterator
+    idx.insert(obj2, obj2_box2_iterator())
+
+    # Both objects should be present
+    results = idx.intersect((0.0, 0.0, 100.0, 100.0))
+    assert set(results) == {obj1, obj2}
+
+    # Try Range
+    obj3 = "obj3"
+    box3_range = range(50, 54)  # 50, 51, 52, 53
+    idx.insert(obj3, box3_range)
+    results = idx.intersect((0.0, 0.0, 100.0, 100.0))
+    assert set(results) == {obj1, obj2, obj3}
+
+
+def test_insert_fails_on_tuple_too_long():
+    """Test that insert fails when bbox tuple is too long."""
+    idx = FQTIndex(bbox=WORLD)
+
+    obj1 = "obj1"
+    box1 = (10.0, 10.0, 20.0, 20.0, 30.0)  # This should fail
+
+    with pytest.raises(ValueError):
+        idx.insert(obj1, box1)
+
+
+def non_tuple_intersect_and_non_tuple_remove_handled():
+    """Test that intersect and remove accept any iterable (not just list/tuple)."""
+    idx = FQTIndex(bbox=WORLD)
+
+    obj1, box1 = "obj1", (10.0, 10.0, 20.0, 20.0)
+
+    idx.insert(obj1, box1)
+
+    def query_iterator():
+        yield 15.0
+        yield 15.0
+        yield 25.0
+        yield 25.0
+
+    results = idx.intersect(query_iterator())
+    assert results == [obj1]
+
+    def remove_box_iterator():
+        yield 10.0
+        yield 10.0
+        yield 20.0
+        yield 20.0
+
+    idx.remove(obj1, remove_box_iterator())
+    assert idx.intersect((0.0, 0.0, 100.0, 100.0)) == []