fastquadtree 0.9.1__cp38-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl → 1.0.1__cp38-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl

fastquadtree/_base_quadtree.py

@@ -2,36 +2,36 @@
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from typing import Any, Generic, Tuple, TypeVar
+from typing import Any, Generic, Iterable, Tuple, TypeVar
 
-from ._bimap import BiMap
 from ._item import Item  # base class for PointItem and RectItem
+from ._obj_store import ObjStore
 
 Bounds = Tuple[float, float, float, float]
 
 # Generic parameters
 G = TypeVar("G")  # geometry type, e.g. Point or Bounds
 HitT = TypeVar("HitT")  # raw native tuple, e.g. (id,x,y) or (id,x0,y0,x1,y1)
-ItemType = TypeVar(
-    "ItemType", bound=Item
-)  # Python Item subtype, e.g. PointItem or RectItem
+ItemType = TypeVar("ItemType", bound=Item)  # e.g. PointItem or RectItem
 
 
 class _BaseQuadTree(Generic[G, HitT, ItemType], ABC):
     """
     Shared logic for Python QuadTree wrappers over native Rust engines.
 
-    Concrete subclasses must implement the few native hooks and item builders.
+    Concrete subclasses must implement:
+      - _new_native(bounds, capacity, max_depth)
+      - _make_item(id_, geom, obj)
     """
 
     __slots__ = (
         "_bounds",
         "_capacity",
         "_count",
-        "_items",
         "_max_depth",
         "_native",
         "_next_id",
+        "_store",
         "_track_objects",
     )
 
@@ -54,78 +54,115 @@ class _BaseQuadTree(Generic[G, HitT, ItemType], ABC):
         *,
         max_depth: int | None = None,
         track_objects: bool = False,
-        start_id: int = 1,
     ):
         self._bounds = bounds
         self._max_depth = max_depth
         self._capacity = capacity
         self._native = self._new_native(bounds, capacity, max_depth)
-        # typed item map if tracking enabled
+
         self._track_objects = bool(track_objects)
-        self._items: BiMap[ItemType] | None = BiMap() if track_objects else None
-        self._next_id = int(start_id)
+        self._store: ObjStore[ItemType] | None = ObjStore() if track_objects else None
+
+        # Auto ids when not using ObjStore.free slots
+        self._next_id = 0
         self._count = 0
 
-    # ---- shared helpers ----
+    # ---- internal helper ----
 
-    def _alloc_id(self, id_: int | None) -> int:
-        if id_ is None:
-            nid = self._next_id
-            self._next_id += 1
-            return nid
-        if id_ >= self._next_id:
-            self._next_id = id_ + 1
-        return id_
+    def _ids_to_objects(self, ids: Iterable[int]) -> list[Any]:
+        """Map ids -> Python objects via ObjStore in a batched way."""
+        if self._store is None:
+            raise ValueError("Cannot map ids to objects when track_objects=False")
+        return self._store.get_many_objects(list(ids))
 
-    def insert(self, geom: G, *, id_: int | None = None, obj: Any = None) -> int:
+    # ---- shared API ----
+
+    def insert(self, geom: G, *, obj: Any | None = None) -> int:
         """
-        Insert a single item
+        Insert a single item.
 
         Args:
             geom: Point (x, y) or Rect (x0, y0, x1, y1) depending on quadtree type.
-            id_: Optional integer id. If None, an auto id is assigned.
-            obj: Optional Python object to associate with id. Stored only if
-                object tracking is enabled.
+            obj: Optional Python object to associate with id if tracking is enabled.
 
         Returns:
             The id used for this insert.
 
         Raises:
-            ValueError: If the point is outside tree bounds.
+            ValueError: If geometry is outside the tree bounds.
         """
-        use_id = self._alloc_id(id_)
-        if not self._native.insert(use_id, geom):
+        if self._store is not None:
+            # Reuse a dense free slot if available, else append
+            rid = self._store.alloc_id()
+        else:
+            rid = self._next_id
+            self._next_id += 1
+
+        if not self._native.insert(rid, geom):
             bx0, by0, bx1, by1 = self._bounds
             raise ValueError(
                 f"Geometry {geom!r} is outside bounds ({bx0}, {by0}, {bx1}, {by1})"
             )
 
-        if self._items is not None:
-            self._items.add(self._make_item(use_id, geom, obj))
+        if self._store is not None:
+            self._store.add(self._make_item(rid, geom, obj))
 
         self._count += 1
-        return use_id
+        return rid
 
-    def insert_many(self, geoms: list[G]) -> int:
+    def insert_many(self, geoms: list[G], objs: list[Any] | None = None) -> int:
         """
-        Bulk insert items with auto-assigned ids. Faster than inserting one at a time.
+        Bulk insert with auto-assigned contiguous ids. Faster than inserting one-by-one.<br>
+
+        If tracking is enabled, the objects will be bulk stored internally.
+        If no objects are provided, the items will have obj=None (if tracking).
 
         Args:
-            geoms: List of geometries. Either Points (x, y) or Rects (x0, y0, x1, y1) depending on quadtree type.
+            geoms: List of geometries.
+            objs: Optional list of Python objects aligned with geoms.
 
         Returns:
-            The number of items inserted
+            Number of items inserted.
+
+        Raises:
+            ValueError: If any geometry is outside bounds.
         """
-        start_id = self._next_id
+        if not geoms:
+            return 0
+
+        if self._store is None:
+            # Simple contiguous path with native bulk insert
+            start_id = self._next_id
+            last_id = self._native.insert_many(start_id, geoms)
+            num = last_id - start_id + 1
+            if num < len(geoms):
+                raise ValueError("One or more items are outside tree bounds")
+            self._next_id = last_id + 1
+            self._count += num
+            return num
+
+        # With tracking enabled:
+        start_id = len(self._store._arr)  # contiguous tail position
         last_id = self._native.insert_many(start_id, geoms)
         num = last_id - start_id + 1
         if num < len(geoms):
             raise ValueError("One or more items are outside tree bounds")
 
-        self._next_id = last_id + 1
-        if self._items is not None:
-            for i, id_ in enumerate(range(start_id, last_id + 1)):
-                self._items.add(self._make_item(id_, geoms[i], None))
+        # Add items to the store in one pass
+        if objs is None:
+            for off, geom in enumerate(geoms):
+                id_ = start_id + off
+                self._store.add(self._make_item(id_, geom, None))
+        else:
+            if len(objs) != len(geoms):
+                raise ValueError("objs length must match geoms length")
+            for off, (geom, o) in enumerate(zip(geoms, objs)):
+                id_ = start_id + off
+                self._store.add(self._make_item(id_, geom, o))
+
+        # Keep _next_id monotonic for the non-tracking path
+        self._next_id = max(self._next_id, last_id + 1)
+
         self._count += num
         return num
 
@@ -133,107 +170,72 @@ class _BaseQuadTree(Generic[G, HitT, ItemType], ABC):
         """
         Delete an item by id and exact geometry.
 
-        Args:
-            id_: Integer id to remove.
-            geom: Exact geometry to remove. Either Point (x, y) or Rect (x0, y0, x1, y1) depending on quadtree type.
-
         Returns:
-            True if the item was found and deleted, else False.
+            True if the item was found and deleted.
         """
         deleted = self._native.delete(id_, geom)
         if deleted:
             self._count -= 1
-            if self._items is not None:
-                self._items.pop_id(id_)
+            if self._store is not None:
+                self._store.pop_id(id_)
         return deleted
 
     def attach(self, id_: int, obj: Any) -> None:
         """
         Attach or replace the Python object for an existing id.
         Tracking must be enabled.
-
-        Args:
-            id_: Target id.
-            obj: Object to associate with id.
         """
-        if self._items is None:
+        if self._store is None:
             raise ValueError("Cannot attach objects when track_objects=False")
-        it = self._items.by_id(id_)
+        it = self._store.by_id(id_)
         if it is None:
             raise KeyError(f"Id {id_} not found in quadtree")
         # Preserve geometry from existing item
-        self._items.add(self._make_item(id_, it.geom, obj))  # type: ignore[attr-defined]
+        self._store.add(self._make_item(id_, it.geom, obj))  # type: ignore[attr-defined]
 
     def delete_by_object(self, obj: Any) -> bool:
         """
-        Delete an item by Python object.
-
-        Requires object tracking to be enabled. Performs an O(1) reverse
-        lookup to get the id, then deletes that entry at the given location.
-
-        Args:
-            obj: The tracked Python object to remove.
-
-        Returns:
-            True if the item was found and deleted, else False.
-
-        Raises:
-            ValueError: If object tracking is disabled.
+        Delete an item by Python object identity. Tracking must be enabled.
         """
-        if self._items is None:
+        if self._store is None:
             raise ValueError("Cannot delete by object when track_objects=False")
-        it = self._items.by_obj(obj)
+        it = self._store.by_obj(obj)
         if it is None:
             return False
-        # type of geom is determined by concrete Item subtype
         return self.delete(it.id_, it.geom)  # type: ignore[arg-type]
 
-    def clear(self, *, reset_ids: bool = False) -> None:
+    def clear(self) -> None:
         """
-        Empty the tree in place, preserving bounds/capacity/max_depth.
+        Empty the tree in place, preserving bounds, capacity, and max_depth.
 
-        Args:
-            reset_ids: If True, restart auto-assigned ids from 1.
+        If tracking is enabled, the id -> object mapping is also cleared.
+        The ids are reset to start at zero again.
         """
         self._native = self._new_native(self._bounds, self._capacity, self._max_depth)
         self._count = 0
-        if self._items is not None:
-            self._items.clear()
-        if reset_ids:
-            self._next_id = 1
+        if self._store is not None:
+            self._store.clear()
+        self._next_id = 0
 
     def get_all_objects(self) -> list[Any]:
         """
         Return all tracked Python objects in the tree.
-
-        Returns:
-            List of objects.
-        Raises:
-            ValueError: If object tracking is disabled.
         """
-        if self._items is None:
+        if self._store is None:
             raise ValueError("Cannot get objects when track_objects=False")
-        return [t.obj for t in self._items.items() if t.obj is not None]
+        return [t.obj for t in self._store.items() if t.obj is not None]
 
     def get_all_items(self) -> list[ItemType]:
         """
         Return all Item wrappers in the tree.
-
-        Returns:
-            List of Item objects.
-        Raises:
-            ValueError: If object tracking is disabled.
         """
-        if self._items is None:
+        if self._store is None:
             raise ValueError("Cannot get items when track_objects=False")
-        return list(self._items.items())
+        return list(self._store.items())
 
     def get_all_node_boundaries(self) -> list[Bounds]:
         """
-        Return all node boundaries in the tree. Great for visualizing the tree structure.
-
-        Returns:
-            List of (min_x, min_y, max_x, max_y) for each node in the tree.
+        Return all node boundaries in the tree. Useful for visualization.
         """
         return self._native.get_all_node_boundaries()
 
@@ -241,21 +243,14 @@ class _BaseQuadTree(Generic[G, HitT, ItemType], ABC):
         """
         Return the object associated with id, if tracking is enabled.
         """
-        if self._items is None:
+        if self._store is None:
             raise ValueError("Cannot get objects when track_objects=False")
-        item = self._items.by_id(id_)
+        item = self._store.by_id(id_)
         return None if item is None else item.obj
 
     def count_items(self) -> int:
         """
-        Return the number of items currently in the tree.
-
-        Note:
-            Performs a full scan of tree to count up every item.
-            Use the `len()` function or `len(tree)` for O(1) access.
-
-        Returns:
-            Number of items in the tree.
+        Return the number of items currently in the tree (native count).
         """
         return self._native.count_items()
 

fastquadtree/_obj_store.py

@@ -0,0 +1,167 @@
+# _bimap.py
+from __future__ import annotations
+
+from operator import itemgetter
+from typing import Any, Generic, Iterable, Iterator, TypeVar
+
+from ._item import Item  # base class for PointItem and RectItem
+
+TItem = TypeVar("TItem", bound=Item)
+
+
+class ObjStore(Generic[TItem]):
+    """
+    High-performance id <-> object store for dense, auto-assigned ids.
+
+    Storage
+      - _arr[id]  -> Item or None
+      - _objs[id] -> Python object or None
+      - _obj_to_id: reverse identity map id(obj) -> id
+      - _free: LIFO free-list of reusable ids
+
+    Assumptions
+      - Ids are assigned by the shim and are dense [0..len) with possible holes
+        created by deletes. New inserts reuse holes via the free-list.
+    """
+
+    __slots__ = ("_arr", "_free", "_len", "_obj_to_id", "_objs")
+
+    def __init__(self, items: Iterable[TItem] | None = None) -> None:
+        self._arr: list[TItem | None] = []
+        self._objs: list[Any | None] = []
+        self._obj_to_id: dict[int, int] = {}
+        self._free: list[int] = []  # LIFO
+        self._len: int = 0  # live items
+
+        if items:
+            for it in items:
+                self.add(it)
+
+    # -------- core --------
+
+    def add(self, item: TItem) -> None:
+        """
+        Insert or replace the mapping at item.id_. Reverse map updated so obj points to id.
+        """
+        id_ = item.id_
+        obj = item.obj
+
+        # 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 id_ == len(self._arr):
+            # append
+            self._arr.append(item)
+            self._objs.append(obj)
+            self._len += 1
+        else:
+            # replace or fill a hole
+            old = self._arr[id_]
+            if old is None:
+                self._len += 1
+            elif old.obj is not None:
+                self._obj_to_id.pop(id(old.obj), None)
+            self._arr[id_] = item
+            self._objs[id_] = obj
+
+        if obj is not None:
+            self._obj_to_id[id(obj)] = id_
+
+    def by_id(self, id_: int) -> TItem | None:
+        return self._arr[id_] if 0 <= id_ < len(self._arr) else None
+
+    def by_obj(self, obj: Any) -> TItem | None:
+        id_ = self._obj_to_id.get(id(obj))
+        return self.by_id(id_) if id_ is not None else None
+
+    def pop_id(self, id_: int) -> TItem | None:
+        """Remove by id. Dense ids go to the free-list for reuse."""
+        if not (0 <= id_ < len(self._arr)):
+            return None
+        it = self._arr[id_]
+        if it is None:
+            return None
+        self._arr[id_] = None
+        self._objs[id_] = None
+        if it.obj is not None:
+            self._obj_to_id.pop(id(it.obj), None)
+        self._free.append(id_)
+        self._len -= 1
+        return it
+
+    # -------- allocation --------
+
+    def alloc_id(self) -> int:
+        """
+        Get a reusable dense id. Uses free-list else appends at the tail.
+        Build your Item with this id then call add(item).
+        """
+        return self._free.pop() if self._free else len(self._arr)
+
+    # -------- fast batch gathers --------
+
+    def get_many_by_ids(self, ids: Iterable[int], *, chunk: int = 2048) -> list[TItem]:
+        """
+        Batch: return Items for ids, preserving order.
+        Uses C-level itemgetter on the dense array in chunks.
+        """
+        ids_list: list[int] = list(ids)
+        if not ids_list:
+            return []
+
+        out: list[TItem] = []
+        extend = out.extend
+        arr = self._arr
+        for i in range(0, len(ids_list), chunk):
+            block = ids_list[i : i + chunk]
+            vals = itemgetter(*block)(arr)  # tuple or single item
+            extend(vals if isinstance(vals, tuple) else (vals,))
+        return out
+
+    def get_many_objects(self, ids: Iterable[int], *, chunk: int = 2048) -> list[Any]:
+        """
+        Batch: return Python objects for ids, preserving order.
+        Mirrors get_many_by_ids but reads from _objs.
+        """
+        ids_list: list[int] = list(ids)
+        if not ids_list:
+            return []
+
+        out: list[Any] = []
+        extend = out.extend
+        objs = self._objs
+        for i in range(0, len(ids_list), chunk):
+            block = ids_list[i : i + chunk]
+            vals = itemgetter(*block)(objs)  # tuple or single object
+            extend(vals if isinstance(vals, tuple) else (vals,))
+        return out
+
+    # -------- convenience and iteration --------
+
+    def __len__(self) -> int:
+        return self._len
+
+    def clear(self) -> None:
+        self._arr.clear()
+        self._objs.clear()
+        self._obj_to_id.clear()
+        self._free.clear()
+        self._len = 0
+
+    def contains_id(self, id_: int) -> bool:
+        return 0 <= id_ < len(self._arr) and self._arr[id_] is not None
+
+    def contains_obj(self, obj: Any) -> bool:
+        return id(obj) in self._obj_to_id
+
+    def items_by_id(self) -> Iterator[tuple[int, TItem]]:
+        for i, it in enumerate(self._arr):
+            if it is not None:
+                yield i, it
+
+    def items(self) -> Iterator[TItem]:
+        for _, it in self.items_by_id():
+            yield it

fastquadtree/point_quadtree.py

@@ -29,7 +29,6 @@ class QuadTree(_BaseQuadTree[Point, _IdCoord, PointItem]):
         capacity: Max number of points per node before splitting.
         max_depth: Optional max tree depth. If omitted, engine decides.
         track_objects: Enable id <-> object mapping inside Python.
-        start_id: Starting auto-assigned id when you omit id on insert.
 
     Raises:
         ValueError: If parameters are invalid or inserts are out of bounds.
@@ -42,14 +41,12 @@ class QuadTree(_BaseQuadTree[Point, _IdCoord, PointItem]):
         *,
         max_depth: int | None = None,
         track_objects: bool = False,
-        start_id: int = 1,
     ):
         super().__init__(
             bounds,
             capacity,
             max_depth=max_depth,
             track_objects=track_objects,
-            start_id=start_id,
         )
 
     @overload
@@ -72,20 +69,11 @@ class QuadTree(_BaseQuadTree[Point, _IdCoord, PointItem]):
             If as_items is False: list of (id, x, y) tuples.
             If as_items is True: list of Item objects.
         """
-        raw = self._native.query(rect)
         if not as_items:
-            return raw
-        if self._items is None:
+            return self._native.query(rect)
+        if self._store is None:
             raise ValueError("Cannot return results as items with track_objects=False")
-        out: list[PointItem] = []
-        for id_, _x, _y in raw:
-            it = self._items.by_id(id_)
-            if it is None:
-                raise RuntimeError(
-                    f"Internal error: id {id_} present in native tree but missing from tracker."
-                )
-            out.append(it)
-        return out
+        return self._store.get_many_by_ids(self._native.query_ids(rect))
 
     @overload
     def nearest_neighbor(
@@ -111,10 +99,10 @@ class QuadTree(_BaseQuadTree[Point, _IdCoord, PointItem]):
         t = self._native.nearest_neighbor(xy)
         if t is None or not as_item:
             return t
-        if self._items is None:
+        if self._store is None:
             raise ValueError("Cannot return result as item with track_objects=False")
         id_, _x, _y = t
-        it = self._items.by_id(id_)
+        it = self._store.by_id(id_)
         if it is None:
             raise RuntimeError("Internal error: missing tracked item")
         return it
@@ -142,11 +130,11 @@ class QuadTree(_BaseQuadTree[Point, _IdCoord, PointItem]):
         raw = self._native.nearest_neighbors(xy, k)
         if not as_items:
             return raw
-        if self._items is None:
+        if self._store is None:
             raise ValueError("Cannot return results as items with track_objects=False")
         out: list[PointItem] = []
         for id_, _x, _y in raw:
-            it = self._items.by_id(id_)
+            it = self._store.by_id(id_)
             if it is None:
                 raise RuntimeError("Internal error: missing tracked item")
             out.append(it)

fastquadtree/pyqtree.py

@@ -5,6 +5,7 @@ drop-in replacement to fastquadtree.
 
 from __future__ import annotations
 
+from operator import itemgetter
 from typing import Any, Tuple
 
 from ._native import RectQuadTree
@@ -16,11 +17,28 @@ MAX_ITEMS = 10
 MAX_DEPTH = 20
 
 
+# Helper to gather objects by ids in chunks
+# Performance improvement over list comprehension for large result sets
+# 2.945 median query time --> 2.030 median query time (500k items, 500 queries)
+def gather_objs(objs, ids, chunk=2048):
+    out = []
+    for i in range(0, len(ids), chunk):
+        getter = itemgetter(*ids[i : i + chunk])
+        vals = getter(objs)  # tuple or single object
+        if isinstance(vals, tuple):
+            out.extend(vals)
+        else:
+            out.append(vals)
+    return out
+
+
 class Index:
     """
     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.
 
 
     The top spatial index to be created by the user. Once created it can be
@@ -30,16 +48,21 @@ class Index:
     all the quad instances and lets you access their properties.
 
     Example usage:
+    ```python
+    from fastquadtree.pyqtree import Index
+
 
-    >>> spindex = Index(bbox=(0, 0, 100, 100))
-    >>> spindex.insert('duck', (50, 30, 53, 60))
-    >>> spindex.insert('cookie', (10, 20, 15, 25))
-    >>> spindex.insert('python', (40, 50, 95, 90))
-    >>> results = spindex.intersect((51, 51, 86, 86))
-    >>> sorted(results)
-    ['duck', 'python']
+    spindex = Index(bbox=(0, 0, 100, 100))
+    spindex.insert('duck', (50, 30, 53, 60))
+    spindex.insert('cookie', (10, 20, 15, 25))
+    spindex.insert('python', (40, 50, 95, 90))
+    results = spindex.intersect((51, 51, 86, 86))
+    sorted(results) # ['duck', 'python']
+    ```
     """
 
+    __slots__ = ("_free", "_item_to_id", "_objects", "_qt")
+
     def __init__(
         self,
         bbox=None,
@@ -87,7 +110,9 @@ class Index:
                 "Either the bbox argument must be set, or the x, y, width, and height arguments must be set"
             )
 
-        self._id_to_obj: dict[int, Any] = {}
+        self._objects = []
+        self._free = []
+        self._item_to_id = {}
 
     def insert(self, item: Any, bbox):  # pyright: ignore[reportIncompatibleMethodOverride]
         """
@@ -97,8 +122,14 @@ class Index:
         - **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)
         """
-        self._id_to_obj[id(item)] = item
-        self._qt.insert(id(item), bbox)
+        if self._free:
+            rid = self._free.pop()
+            self._objects[rid] = item
+        else:
+            rid = len(self._objects)
+            self._objects.append(item)
+        self._qt.insert(rid, bbox)
+        self._item_to_id[id(item)] = rid
 
     def remove(self, item, bbox):
         """
@@ -110,10 +141,10 @@ class Index:
 
         Both parameters need to exactly match the parameters provided to the insert method.
         """
-        self._qt.delete(id(item), bbox)
-
-        # Pops
-        self._id_to_obj.pop(id(item), None)
+        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):
         """
@@ -126,6 +157,6 @@ class Index:
         Returns:
         - A list of inserted items whose bounding boxes intersect with the input bbox.
         """
-        results = self._qt.query(bbox)
-        # result = (id, x0, y0, x1, y1)
-        return [self._id_to_obj[result[0]] for result in results]
+        result = self._qt.query_ids(bbox)
+        # result = [id1, id2, ...]
+        return gather_objs(self._objects, result)

fastquadtree/rect_quadtree.py

@@ -30,7 +30,6 @@ class RectQuadTree(_BaseQuadTree[Bounds, _IdRect, RectItem]):
         capacity: Max number of points per node before splitting.
         max_depth: Optional max tree depth. If omitted, engine decides.
         track_objects: Enable id <-> object mapping inside Python.
-        start_id: Starting auto-assigned id when you omit id on insert.
 
     Raises:
         ValueError: If parameters are invalid or inserts are out of bounds.
@@ -43,14 +42,12 @@ class RectQuadTree(_BaseQuadTree[Bounds, _IdRect, RectItem]):
         *,
         max_depth: int | None = None,
         track_objects: bool = False,
-        start_id: int = 1,
     ):
         super().__init__(
             bounds,
             capacity,
             max_depth=max_depth,
             track_objects=track_objects,
-            start_id=start_id,
         )
 
     @overload
@@ -73,23 +70,11 @@ class RectQuadTree(_BaseQuadTree[Bounds, _IdRect, RectItem]):
             If as_items is False: list of (id, x0, y0, x1, y1) tuples.
             If as_items is True: list of Item objects.
         """
-        raw = self._native.query(rect)
         if not as_items:
-            return raw
-        if self._items is None:
-            # Build RectItem without objects
-            return [
-                RectItem(id_, (x0, y0, x1, y1), None) for (id_, x0, y0, x1, y1) in raw
-            ]
-        out: list[RectItem] = []
-        for id_, _x0, _y0, _x1, _y1 in raw:
-            it = self._items.by_id(id_)
-            if it is None:
-                raise RuntimeError(
-                    f"Internal error: id {id_} present in native tree but missing from tracker."
-                )
-            out.append(it)
-        return out
+            return self._native.query(rect)
+        if self._store is None:
+            raise ValueError("Cannot return results as items with track_objects=False")
+        return self._store.get_many_by_ids(self._native.query_ids(rect))
 
     def _new_native(self, bounds: Bounds, capacity: int, max_depth: int | None) -> Any:
         if max_depth is None:

{fastquadtree-0.9.1.dist-info → fastquadtree-1.0.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastquadtree
-Version: 0.9.1
+Version: 1.0.1
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Rust
@@ -69,6 +69,7 @@ Rust-optimized quadtree with a clean Python API
 - Fast KNN and range queries
 - Optional object tracking for id ↔ object mapping
 - [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
 
 ----
 
@@ -86,6 +87,7 @@ pip install fastquadtree
 ```python
 from fastquadtree import QuadTree  # Point handling
 from fastquadtree import RectQuadTree  # Bounding box handling
+from fastquadtree.pyqtree import Index  # Drop-in pyqtree shim (6.567x faster while keeping the same API)
 ```
 
 ## Benchmarks

fastquadtree-1.0.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+fastquadtree-1.0.1.dist-info/METADATA,sha256=L9xfkCTXamefk_ZfyX8caAg6_Su65hYzQlElY8gV-ws,9367
+fastquadtree-1.0.1.dist-info/WHEEL,sha256=xBqaWU3Z-cfW-EFy0ENuEqxgXZXkIHUBkA1cT6FlqGM,127
+fastquadtree-1.0.1.dist-info/licenses/LICENSE,sha256=pRuvcuqIMtEUBMgvP1Bc4fOHydzeuA61c6DQoQ1pb1w,1071
+fastquadtree/__init__.py,sha256=rtkveNz7rScRasTRGu1yEqzeoJfLfreJNxg21orPL-U,195
+fastquadtree/_base_quadtree.py,sha256=tP6pymgV6s29C_1TjCZ6u0XKb6NFq3tQ7tk6REKS020,8576
+fastquadtree/_item.py,sha256=0dxvqAMa94Zg-ZjYVMeZJt-irpafalrXph_Qeqp40AU,1348
+fastquadtree/_native.abi3.so,sha256=M62NxHShvDaMHVyXSc7zaE-UoFfAyS_biELFMHZYeJI,463388
+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=W5akt9gua7mr51eI-I1hqbZJMRdcNKWzpeaZhlOvhb0,5781
+fastquadtree/rect_quadtree.py,sha256=7F-JceCHn5RLhztxSYCIJEZ_e2TV-NeobobbrdauJQA,3024
+fastquadtree-1.0.1.dist-info/RECORD,,

fastquadtree/_bimap.py

@@ -1,112 +0,0 @@
-# _bimap.py
-from __future__ import annotations
-
-from typing import Any, Generic, Iterable, Iterator, TypeVar
-
-from ._item import Item  # base class for PointItem and RectItem
-
-TItem = TypeVar("TItem", bound=Item)
-
-
-class BiMap(Generic[TItem]):
-    """
-    Bidirectional map to the same Item subtype:
-      id -> Item
-      obj -> Item  (uses object identity)
-
-    Rules:
-      - One-to-one: an id maps to exactly one Item, and an object maps to exactly one Item.
-      - add(item): inserts or replaces both sides so they point to 'item'.
-      - If item.obj is None, only id -> Item is stored.
-    """
-
-    __slots__ = ("_id_to_item", "_objid_to_item")
-
-    def __init__(
-        self,
-        items: Iterable[TItem] | None = None,
-    ) -> None:
-        self._id_to_item: dict[int, TItem] = {}
-        self._objid_to_item: dict[int, TItem] = {}
-        if items:
-            for it in items:
-                self.add(it)
-
-    # - core -
-
-    def add(self, item: TItem) -> None:
-        """
-        Insert or replace mapping for this Item.
-        Handles conflicts so both id and obj point to this exact Item.
-        """
-        id_ = item.id_
-        obj = item.obj
-
-        # Unlink any old item currently bound to this id
-        old = self._id_to_item.get(id_)
-        if old is not None and old is not item:
-            old_obj = old.obj
-            if old_obj is not None:
-                self._objid_to_item.pop(id(old_obj), None)
-
-        # Unlink any old item currently bound to this obj
-        if obj is not None:
-            prev = self._objid_to_item.get(id(obj))
-            if prev is not None and prev is not item:
-                self._id_to_item.pop(prev.id_, None)
-
-        # Link new
-        self._id_to_item[id_] = item
-        if obj is not None:
-            self._objid_to_item[id(obj)] = item
-
-    def by_id(self, id_: int) -> TItem | None:
-        return self._id_to_item.get(id_)
-
-    def by_obj(self, obj: Any) -> TItem | None:
-        return self._objid_to_item.get(id(obj))
-
-    def pop_id(self, id_: int) -> TItem | None:
-        it = self._id_to_item.pop(id_, None)
-        if it is not None:
-            obj = it.obj
-            if obj is not None:
-                self._objid_to_item.pop(id(obj), None)
-        return it
-
-    def pop_obj(self, obj: Any) -> TItem | None:
-        it = self._objid_to_item.pop(id(obj), None)
-        if it is not None:
-            self._id_to_item.pop(it.id_, None)
-        return it
-
-    def pop_item(self, item: TItem) -> TItem | None:
-        """
-        Remove this exact Item if present on either side.
-        """
-        removed = self._id_to_item.pop(item.id_, None)
-        obj = item.obj
-        if obj is not None:
-            self._objid_to_item.pop(id(obj), None)
-        return removed
-
-    # - convenience -
-
-    def __len__(self) -> int:
-        return len(self._id_to_item)
-
-    def clear(self) -> None:
-        self._id_to_item.clear()
-        self._objid_to_item.clear()
-
-    def contains_id(self, id_: int) -> bool:
-        return id_ in self._id_to_item
-
-    def contains_obj(self, obj: Any) -> bool:
-        return id(obj) in self._objid_to_item
-
-    def items_by_id(self) -> Iterator[tuple[int, TItem]]:
-        return iter(self._id_to_item.items())
-
-    def items(self) -> Iterator[TItem]:
-        return iter(self._id_to_item.values())

fastquadtree-0.9.1.dist-info/RECORD

@@ -1,13 +0,0 @@
-fastquadtree-0.9.1.dist-info/METADATA,sha256=ZUdCmtvzf7fHofYIKv0A6txQ78-ODxVkghW_3Qdpi8w,9088
-fastquadtree-0.9.1.dist-info/WHEEL,sha256=xBqaWU3Z-cfW-EFy0ENuEqxgXZXkIHUBkA1cT6FlqGM,127
-fastquadtree-0.9.1.dist-info/licenses/LICENSE,sha256=pRuvcuqIMtEUBMgvP1Bc4fOHydzeuA61c6DQoQ1pb1w,1071
-fastquadtree/__init__.py,sha256=rtkveNz7rScRasTRGu1yEqzeoJfLfreJNxg21orPL-U,195
-fastquadtree/_base_quadtree.py,sha256=MCXkrEnMqZmYLRAChVsjBu_R9n-bvclPmgmwTscZpzQ,8413
-fastquadtree/_bimap.py,sha256=7QBJ3QzEQq69PhKNA2W04N37i3-oNleEyb_qSXGSecw,3327
-fastquadtree/_item.py,sha256=0dxvqAMa94Zg-ZjYVMeZJt-irpafalrXph_Qeqp40AU,1348
-fastquadtree/_native.abi3.so,sha256=Dpf7Yo9ThxYSj9y3yyKFTbrde9GMFtaNegUblIuJbEA,460780
-fastquadtree/point_quadtree.py,sha256=3bW4Apol-0TKSYF4IJ5KLbn9mhLEFSQT7P-rD9H6vuc,5583
-fastquadtree/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-fastquadtree/pyqtree.py,sha256=Q2b1Ixc9u4d6_YM6-40i3TSkIo4PxYQdoG96I6TC0A4,4725
-fastquadtree/rect_quadtree.py,sha256=fVjb5o8kl3s2FwuzpaaMeUV2Ni_h7uxjJNeWdJTNWws,3519
-fastquadtree-0.9.1.dist-info/RECORD,,