improve style across library

Author: pranav-walimbe

Makefile

@@ -2,30 +2,30 @@
 
 sources = python/ tests/python/ bench/
 
-# Preserve colour in cargo output when running from a tty
+# Preserve color in cargo output when running from a tty
 export CARGO_TERM_COLOR=$(shell (test -t 0 && echo "always") || echo "auto")
 
 .PHONY: setup ## Create .venv and install dev dependencies from uv.lock
 setup:
 	uv sync --group dev
 
-.PHONY: format ## Auto-format Rust and Python source files
+.PHONY: format
 format:
 	cargo fmt
 	uv run ruff check --fix $(sources)
 	uv run ruff format $(sources)
 
-.PHONY: lint-python ## Lint Python source files
+.PHONY: lint-python
 lint-python:
 	uv run ruff check $(sources)
 	uv run ruff format --check $(sources)
 
-.PHONY: lint-rust ## Lint Rust source files (fmt check + clippy over all code incl. tests)
+.PHONY: lint-rust
 lint-rust:
 	cargo fmt --all -- --check
 	cargo clippy --tests -- -D warnings
 
-.PHONY: lint ## Lint Rust and Python source files
+.PHONY: lint
 lint: lint-python lint-rust
 
 .PHONY: build ## Debug build
@@ -39,26 +39,24 @@ build-prod:
 	uv run maturin develop --release
 
 # Build first so clippy and cargo nextest reuse compiled objects from maturin
-# instead of each triggering a second Rust compile pass.
-# sccache (via RUSTC_WRAPPER in .cargo/config.toml) caches across runs.
-.PHONY: check ## Format, build, lint, and test — run before every commit
+.PHONY: check
 check: format build lint
 	cargo nextest run
 	uv run pytest tests/python/ --durations=5
 
-.PHONY: test ## Build and run all tests without formatting or linting
+.PHONY: test
 test: build
 	cargo nextest run
 	uv run pytest tests/python/
 
-.PHONY: clean ## Remove build artifacts and caches
+.PHONY: clean
 clean:
 	rm -rf `find . -name __pycache__`
 	rm -f `find . -type f -name '*.py[co]'`
 	rm -rf .pytest_cache .ruff_cache
 	rm -f python/pycanopy/*.so
 
-.PHONY: help ## Display this help message
+.PHONY: help
 help:
 	@grep -E '^\.PHONY: .*?## .*$$' $(MAKEFILE_LIST) | \
 	awk 'BEGIN {FS = ".PHONY: |## "}; {printf "\033[36m%-15s\033[0m %s\n", $$2, $$3}'

README.md

@@ -45,7 +45,9 @@ result = sf.lazy().filter(pl.col("population") > 100_000).range_query(-10.0, 35.
 
 ## Why PyCanopy
 
-The only spatial engine with a Polars-native API, cost-model-driven index selection, and a full spatial query planner. The driving motivator behind creating this library was to provide the optimizations of relational DBs (query planning, indexing) in a performant dataframe interface that abstracts away the complexity of doing so from users working with spatial data. 
+PyCanopy is the only spatial engine with a Polars-native API, cost-model-driven index selection, and a full spatial query planner.
+
+The driving motivator behind creating this library was to provide the optimizations of relational DBs (query planning, indexing, etc) in a performant dataframe interface that abstracts away the complexity of doing so from users working with spatial data.
 
 |  | PyCanopy | GeoPandas | DuckDB | SedonaDB | Spatial Polars |
 |:--|:--------:|:---------:|:------:|:--------:|:--------------:|

python/pycanopy/agg.py

@@ -1,5 +1,5 @@
-"""Aggregation specs for the fused aggregate-join (SpatialGroupBy.agg).
-
+"""
+Aggregation specs for the fused aggregate-join (SpatialGroupBy.agg).
 Specs are associative so partials fold over the streamed join without materialising the full pair frame.
 """
 
@@ -9,7 +9,7 @@
 
 import polars as pl
 
-# Prefix for intermediate (partial) columns, kept distinct from user output names
+# Prefix for intermediate (partial) columns
 _P = "__pc_agg__"
 
 

python/pycanopy/engine.py

@@ -1,4 +1,5 @@
-"""High-level Python engine wrapping the Rust core.
+"""
+High-level Python engine wrapping the Rust core.
 
 Normalizes varied point input to contiguous float64 arrays, with standard 2D LE WKB decoding via a strided numpy view.
 """
@@ -201,8 +202,7 @@ def _wkb_binary_buffers(column) -> tuple[np.ndarray, np.ndarray] | None:
 def _extract_polygon_rings(
     geometries,
 ) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray | None]:
-    # Return (xs, ys, ring_offsets, poly_offsets, part_poly) from Polygons/MultiPolygons via
-    # two-level GeoArrow-compatible offsets, with part_poly mapping parts to logical polygons.
+    # Return (xs, ys, ring_offsets, poly_offsets, part_poly) from Polygons/MultiPolygons
     geoms = np.asarray(geometries)
     type_ids = shapely.get_type_id(geoms)
     invalid = (type_ids != _SHAPELY_POLYGON_TYPE_ID) & (type_ids != _SHAPELY_MULTIPOLYGON_TYPE_ID)
@@ -296,7 +296,7 @@ def from_polygons(cls, geometries) -> Engine:
                 as one logical polygon spanning all of its parts.
 
         Returns:
-            Engine ready to answer range and contains queries over polygon data.
+            Engine object over polygon data.
         """
         xs, ys, ring_offsets, poly_offsets, part_poly = _extract_polygon_rings(geometries)
         eng = cls.__new__(cls)
@@ -312,8 +312,7 @@ def from_wkb_polygons(cls, column) -> Engine:
                 Polygon / MultiPolygon geometries.
 
         Returns:
-            Engine over the polygon data. Falls back to the shapely path for nulls or
-            WKB variants the fast decoder does not recognise.
+            Engine object over polygon data.
         """
         eng = cls.__new__(cls)
         buffers = _wkb_binary_buffers(column)
@@ -338,7 +337,7 @@ def from_wkb_points(cls, points) -> Engine:
                 numpy object array of WKB byte strings.
 
         Returns:
-            Engine ready to answer point queries.
+            Engine object over coord data.
         """
         xs, ys = wkb_points_to_xy(points)
         return cls.from_coords(xs, ys)
@@ -352,7 +351,7 @@ def from_coords(cls, xs: Sequence[float], ys: Sequence[float]) -> Engine:
             ys: Sequence of y coordinates.
 
         Returns:
-            Engine ready to answer point queries.
+            Engine object over coord data.
         """
         eng = cls.__new__(cls)
         eng._core = _CoreEngine.from_points(
@@ -375,7 +374,7 @@ def set_index_mode(self, mode: str) -> str:
             mode: "auto", "eager", or "none".
 
         Returns:
-            The mode in effect before this call.
+            The previous index mode.
         """
         return self._core.set_index_mode(mode)
 

python/pycanopy/executor.py

@@ -1,4 +1,6 @@
-"""Define SpatialExecutor which walks the optimised plan and emits a Polars LazyFrame chain."""
+"""
+Define SpatialExecutor which walks the optimised plan and emits a Polars LazyFrame chain.
+"""
 
 from __future__ import annotations
 
@@ -39,7 +41,7 @@
     PolygonKnnJoinNode,
 )
 
-# Probe rows per morsel for a streamed join. Conservative fixed cap (bounds rows not pairs), overridable via batch_size
+# Probe rows per morsel for a streamed join
 MORSEL_ROWS = 262_144
 
 
@@ -185,24 +187,21 @@ def _execute_body(
     ) -> pl.DataFrame:
         # Run the optimised plan, dispatching scalar / IO / EXPR / streamed-join paths
 
-        # Scalar-only fast path with no spatial ops. Feed filters straight to Polars as a
-        # zero-copy lazy chain (no _ROW_IDX, no dispatch, no bitmap).
+        # Scalar-only fast path with no spatial ops
         if all(isinstance(n, ScalarNode) for n in plan):
             lf = sf.df.lazy()
             for node in plan:
                 lf = lf.filter(node.expr)
             return lf.collect()
 
-        # Intersects self-join is terminal and produces a pair frame, not a row
-        # subset, so it is handled directly rather than through the filter chain.
+        # Intersects self-join is terminal and produces a pair frame
         if any(isinstance(n, IntersectsSelfJoinNode) for n in plan):
             return self._execute_intersects(plan, sf)
 
         has_joins = any(isinstance(n, _JOIN_TYPES) for n in plan)
 
         # Large-probe joins stream the probe in morsels and concatenate, so the join
-        # intermediate is bounded by one morsel rather than the full result. Small
-        # probes fall through to the single-shot path below (no slicing overhead).
+        # intermediate is bounded by one morsel rather than the full result.
         if has_joins:
             morsel = batch_size if batch_size is not None else MORSEL_ROWS
             join_node = next(n for n in plan if isinstance(n, _JOIN_TYPES))
@@ -213,8 +212,7 @@ def _execute_body(
                 return pl.concat(frames, how="vertical", rechunk=False)
 
         # EXPR needs x_col/y_col as real columns (point datasets). Polygon frames use
-        # synthetic coord names absent from df and degrade to IO. Joins bypass the plugin
-        # machinery and stay on EXPR.
+        # synthetic coord names absent from df and degrade to IO.
         if plugin_path == PluginPath.EXPR and sf.x_col not in sf.df.columns and not has_joins:
             plugin_path = PluginPath.IO
 
@@ -262,8 +260,8 @@ def _stream_join_frames(
         join_pos = next(i for i, n in enumerate(plan) if isinstance(n, _JOIN_TYPES))
         join_node = plan[join_pos]
         post_nodes = plan[join_pos + 1 :]
-        # Join emitters ignore the incoming lf (they gather from sf.df directly), so a
-        # placeholder is fine, post-join nodes receive the real joined lf.
+
+        # Join emitters ignore the incoming lf (they gather from sf.df directly)
         placeholder = sf.df.lazy()
         for chunk in join_node.query_df.iter_slices(morsel_rows):
             sub = dataclasses.replace(join_node, query_df=chunk)
@@ -322,7 +320,6 @@ def _execute_io(self, plan: Plan, sf) -> pl.DataFrame:
 
     def _execute_intersects(self, plan: Plan, sf) -> pl.DataFrame:
         # Build the polygon intersects pair frame, then apply any trailing scalar filters.
-        # The self-join takes no probe side, so only scalar nodes after it constrain the result.
         pos = next(i for i, n in enumerate(plan) if isinstance(n, IntersectsSelfJoinNode))
         lf = sf.intersects_pairs().lazy()
         for node in plan[pos + 1 :]:

python/pycanopy/frame.py

@@ -180,9 +180,7 @@ def range_filter(
             return SpatialFrame.from_wkb_polygons(filtered, self._wkb_col, self._x_col, self._y_col)
         return SpatialFrame(self._df[idx_s], self._x_col, self._y_col)
 
-    # Geometry aggregations and transforms (polygon datasets). These produce new
-    # tables or scalar columns rather than filtering, so they live on the frame
-    # rather than the lazy plan.
+    # Geometry aggregations and transforms (polygon datasets)
 
     def polygon_areas(self) -> pl.DataFrame:
         """Append an unsigned 'area' column to this frame's DataFrame (polygon datasets).

python/pycanopy/lazy.py

@@ -1,4 +1,6 @@
-"""Define SpatialLazyFrame, an immutable plan builder that does not execute until .collect()."""
+"""
+Define SpatialLazyFrame, an immutable plan builder that does not execute until .collect().
+"""
 
 from __future__ import annotations
 
@@ -527,7 +529,7 @@ def collect_all(frames: list[SpatialLazyFrame]) -> list[pl.DataFrame]:
         if prefix_len == 0:
             return [f.collect() for f in frames]
 
-        # Optimise the shared prefix as a standalone plan and cache its Polars chain
+        # Optimize the shared prefix as a standalone plan and cache its Polars chain
         prefix_plan = plans[0][:prefix_len]
         optimized_prefix = optimizer.optimize(prefix_plan, sf.engine)
         base_lf = sf.df.with_row_index(_ROW_IDX).lazy()

python/pycanopy/nodes.py

@@ -1,4 +1,5 @@
-"""Plan node types for the SpatialOptimizer.
+"""
+Plan node types for the SpatialOptimizer.
 
 Declaration order is not execution order, the optimizer reorders by selectivity before emitting the final chain.
 """

python/pycanopy/optimizer.py

@@ -1,12 +1,12 @@
-"""SpatialOptimizer: cost-based plan transformer.
+"""
+SpatialOptimizer: cost-based plan transformer.
 
 Passes (in order):
   1. _assign_selectivity: estimate selectivity for each node from engine stats
   2. _cost_sort: reorder scalar vs. spatial based on selectivity
   3. _fusion_pass: merge consecutive fusable spatial nodes
   4. _join_side_pass: set flip=True on symmetric joins where query side is larger
   5. _detect_fanout: find the longest shared plan prefix across branches
-     (used by collect_all to insert a Polars .cache() barrier).
 """
 
 from __future__ import annotations
@@ -31,17 +31,13 @@
     WithinJoinNode,
 )
 
-# Spatial nodes with selectivity below this threshold are too selective to fuse. Polars'
-# cascade leaves so few rows that a fresh index build on survivors beats the full M rows.
+# Spatial nodes with selectivity below this threshold are too selective to fuse
 _FUSION_SELECTIVITY_FLOOR = 0.05
 
-# Datasets smaller than this always use BruteForce, fusion overhead isn't worth it
+# Datasets smaller than this always use BruteForce
 _FUSION_MIN_N = 500
 
-# Spatial selectivity below this threshold means the spatial filter is tighter than
-# 5% of the dataset. The pre-built Engine index on N rows returns so few candidates
-# that slicing sf.df directly (IO path) is cheaper than rebuilding a local index on
-# M post-scalar rows and running a map_batches expression (EXPR path).
+# Spatial selectivity threshold where slicing sf.df directly (IO path) is cheaper
 _IO_SELECTIVITY_THRESHOLD = 0.05
 
 
@@ -152,8 +148,7 @@ def optimize(self, plan: Plan, engine) -> Plan:
         return plan
 
     def _assign_selectivity(self, plan: Plan, engine) -> Plan:
-        # Estimate and attach selectivity to each node. Spatial nodes use area-ratio or k/N
-        # estimates from engine stats, and scalar nodes default to 1.0.
+        # Estimate and attach selectivity to each node
         n = engine.n
         extent = engine.extent
         result = []

src/index/brute.rs

@@ -78,7 +78,6 @@ impl BruteForce {
 
     /// Build from two-level polygon ring arrays. Computes per-polygon MBRs and centroids
     /// from exterior rings only. Holes do not expand the MBR.
-    /// These are derived allocations (N = n_polygons, not N = n_ring_vertices).
     pub fn build_polygons(
         xs: &[f64],
         ys: &[f64],