core-lens 0.1.dev117__tar.gz → 0.1.dev120__tar.gz

{core_lens-0.1.dev117 → core_lens-0.1.dev120}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: core-lens
-Version: 0.1.dev117
+Version: 0.1.dev120
 Summary: Query, analyse, and visualise CoreStack's microwatershed and Earth science data through a clean, composable Python API.
 Project-URL: Homepage, https://github.com/ApoorvaKashyap/core-lens
 Project-URL: Issues, https://github.com/ApoorvaKashyap/core-lens/issues
@@ -17,6 +17,7 @@ Requires-Python: >=3.13
 Requires-Dist: core-lens[core]
 Requires-Dist: core-lens[spatial]
 Provides-Extra: core
+Requires-Dist: loguru>=0.7.3; extra == 'core'
 Requires-Dist: polars<2,>=1.39.0; extra == 'core'
 Requires-Dist: pyarrow<25,>=23.0.0; extra == 'core'
 Requires-Dist: pydantic<3,>=2.13.3; extra == 'core'
@@ -25,6 +26,7 @@ Requires-Dist: bokeh<4,>=3.6.0; extra == 'full'
 Requires-Dist: duckdb<2,>=1.5.3; extra == 'full'
 Requires-Dist: geoarrow-rust-core>=0.3.0; extra == 'full'
 Requires-Dist: geopandas<2,>=1.1.3; extra == 'full'
+Requires-Dist: loguru>=0.7.3; extra == 'full'
 Requires-Dist: lonboard<1,>=0.16.0; extra == 'full'
 Requires-Dist: matplotlib<4,>=3.10.9; extra == 'full'
 Requires-Dist: polars<2,>=1.39.0; extra == 'full'
@@ -41,6 +43,7 @@ Requires-Dist: cudf-polars-cu13==26.6.*; extra == 'full-gpu'
 Requires-Dist: duckdb<2,>=1.5.3; extra == 'full-gpu'
 Requires-Dist: geoarrow-rust-core>=0.3.0; extra == 'full-gpu'
 Requires-Dist: geopandas<2,>=1.1.3; extra == 'full-gpu'
+Requires-Dist: loguru>=0.7.3; extra == 'full-gpu'
 Requires-Dist: lonboard<1,>=0.16.0; extra == 'full-gpu'
 Requires-Dist: matplotlib<4,>=3.10.9; extra == 'full-gpu'
 Requires-Dist: polars<2,>=1.39.0; extra == 'full-gpu'
@@ -53,18 +56,21 @@ Requires-Dist: statsmodels<1,>=0.14.6; extra == 'full-gpu'
 Provides-Extra: gpu
 Requires-Dist: cudf-cu13==26.6.*; extra == 'gpu'
 Requires-Dist: cudf-polars-cu13==26.6.*; extra == 'gpu'
+Requires-Dist: loguru>=0.7.3; extra == 'gpu'
 Requires-Dist: polars<2,>=1.39.0; extra == 'gpu'
 Requires-Dist: pyarrow<25,>=23.0.0; extra == 'gpu'
 Requires-Dist: pydantic<3,>=2.13.3; extra == 'gpu'
 Provides-Extra: spatial
 Requires-Dist: duckdb<2,>=1.5.3; extra == 'spatial'
 Requires-Dist: geopandas<2,>=1.1.3; extra == 'spatial'
+Requires-Dist: loguru>=0.7.3; extra == 'spatial'
 Requires-Dist: polars<2,>=1.39.0; extra == 'spatial'
 Requires-Dist: pyarrow<25,>=23.0.0; extra == 'spatial'
 Requires-Dist: pydantic<3,>=2.13.3; extra == 'spatial'
 Requires-Dist: pyproj<4,>=3.7.2; extra == 'spatial'
 Requires-Dist: shapely<3,>=2.1.2; extra == 'spatial'
 Provides-Extra: stats
+Requires-Dist: loguru>=0.7.3; extra == 'stats'
 Requires-Dist: polars<2,>=1.39.0; extra == 'stats'
 Requires-Dist: pyarrow<25,>=23.0.0; extra == 'stats'
 Requires-Dist: pydantic<3,>=2.13.3; extra == 'stats'
@@ -73,6 +79,7 @@ Requires-Dist: statsmodels<1,>=0.14.6; extra == 'stats'
 Provides-Extra: viz
 Requires-Dist: bokeh<4,>=3.6.0; extra == 'viz'
 Requires-Dist: geoarrow-rust-core>=0.3.0; extra == 'viz'
+Requires-Dist: loguru>=0.7.3; extra == 'viz'
 Requires-Dist: lonboard<1,>=0.16.0; extra == 'viz'
 Requires-Dist: matplotlib<4,>=3.10.9; extra == 'viz'
 Requires-Dist: polars<2,>=1.39.0; extra == 'viz'

{core_lens-0.1.dev117 → core_lens-0.1.dev120}/docs/source/index.rst

@@ -23,4 +23,5 @@ Provides a unified interface over microwatershed hydrology, administrative bound
    plots
    export
    plugins
+   logging
    autoapi/index

core_lens-0.1.dev120/docs/source/logging.md

@@ -0,0 +1,32 @@
+# Logging
+
+`core_lens` uses [Loguru](https://loguru.readthedocs.io/) for internal logging and tracing.
+
+To avoid polluting the standard output of your downstream applications, the logger is disabled by default upon import.
+
+## Enabling Logs
+
+If you want to view the internal tracing logs (useful for debugging spatial resolution issues, inspecting generated time filters, or tracing validation errors), you need to explicitly enable the `core_lens` logger in your application and add a handler (e.g., `sys.stdout` or a log file).
+
+```python
+import sys
+from loguru import logger
+from core_lens import AoI
+
+# 1. Enable the internal logger
+logger.enable("core_lens")
+
+# 2. Add a handler with your desired level and formatting
+logger.add(sys.stdout, level="DEBUG")
+
+# 3. Operations will now emit tracing logs
+aoi = AoI("data/", tehsil="Pangi", district="Chamba")
+```
+
+## Log Levels
+
+`core_lens` emits logs at different levels depending on the operational context:
+
+- **INFO**: Materialisation events (reading static, annual, or fortnightly Parquet files), entity registrations, AoI initialisation, and cross-entity spatial joins.
+- **DEBUG**: Sub-operations such as spatial bounding box index generation, exact geometry relationships, lazy attribute filters, and query generation.
+- **ERROR**: Incorrect initialisation arguments, failed path validations, missing geometries, unknown schema structures, or conflicting date configurations.

{core_lens-0.1.dev117 → core_lens-0.1.dev120}/pyproject.toml

@@ -44,7 +44,12 @@ venvPath = "."
 venv = ".venv"
 
 [project.optional-dependencies]
-core = ["polars>=1.39.0,<2", "pyarrow>=23.0.0,<25", "pydantic>=2.13.3,<3"]
+core = [
+    "polars>=1.39.0,<2",
+    "pyarrow>=23.0.0,<25",
+    "pydantic>=2.13.3,<3",
+    "loguru>=0.7.3",
+]
 spatial = [
     "core-lens[core]",
     "duckdb>=1.5.3,<2",

{core_lens-0.1.dev117 → core_lens-0.1.dev120}/src/core_lens/__init__.py

@@ -6,4 +6,8 @@ except ImportError:
 from core_lens.aoi import AoI, SeasonConfig
 from core_lens.entities.tehsil import TehsilEntity
 
+from loguru import logger
+
+logger.disable("core_lens")
+
 __all__ = ["__version__", "AoI", "SeasonConfig", "TehsilEntity"]

{core_lens-0.1.dev117 → core_lens-0.1.dev120}/src/core_lens/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.1.dev117'
-__version_tuple__ = version_tuple = (0, 1, 'dev117')
+__version__ = version = '0.1.dev120'
+__version_tuple__ = version_tuple = (0, 1, 'dev120')
 
 __commit_id__ = commit_id = None

{core_lens-0.1.dev117 → core_lens-0.1.dev120}/src/core_lens/aoi.py

@@ -12,6 +12,7 @@ if TYPE_CHECKING:
     from core_lens.base.result import Result
 
 import polars as pl
+from loguru import logger
 
 from core_lens.base.entity import BaseEntity, EntityValidationError
 
@@ -177,6 +178,7 @@ class AoI:
         """
         self.data_root = pathlib.Path(data_root).resolve()
         self.seasons: SeasonConfig = seasons or SeasonConfig()
+        logger.info("Initializing AoI with data_root={}", self.data_root)
 
         n_modes = sum(
             [
@@ -186,11 +188,13 @@ class AoI:
             ]
         )
         if n_modes == 0:
+            logger.error("AoI initialization failed: no boundary argument supplied.")
             raise ValueError(
                 "AoI requires exactly one boundary argument: "
                 "bbox=, geometry=, or entity keyword filters such as tehsil='Pangi'."
             )
         if n_modes > 1:
+            logger.error("AoI initialization failed: multiple boundary modes supplied.")
             raise ValueError(
                 "bbox, geometry, and entity keyword filters are mutually exclusive. "
                 "Provide exactly one boundary mode."
@@ -320,6 +324,8 @@ class AoI:
         """
         import shapely.ops as sops
 
+        logger.debug("Resolving named boundary using kwargs: {}", entity_kwargs)
+
         # Find the registered entity whose key_col or known attribute column
         # matches one of the filter keys.
         candidate: BaseEntity | None = None
@@ -335,12 +341,19 @@ class AoI:
         # Fall back: look for an entity whose name matches a kwarg key
         # (e.g. tehsil="Pangi" → TehsilEntity if registered as "tehsil").
         if candidate is None:
+            logger.debug(
+                "No direct column match found for kwargs, attempting entity name fallback"
+            )
             for name, entity in self._entity_instances.items():
                 if name in entity_kwargs:
                     candidate = entity
                     break
 
         if candidate is None:
+            logger.error(
+                "Boundary resolution failed: no registered entity matched filters {}",
+                entity_kwargs,
+            )
             raise EntityValidationError(
                 f"No registered entity can satisfy the filters {entity_kwargs}. "
                 f"Registered entities: {sorted(_REGISTRY)}."
@@ -367,6 +380,9 @@ class AoI:
         df = lf.filter(filter_expr).select(candidate.key_cols + [geom_col]).collect()
 
         if df.is_empty():
+            logger.error(
+                "Boundary resolution failed: no rows matched filters {}", entity_kwargs
+            )
             raise ValueError(
                 f"No rows matched the filters {entity_kwargs} "
                 f"in {candidate.static_path!r}."
@@ -401,6 +417,7 @@ class AoI:
         import pathlib as _pathlib
 
         name = _entity_name(entity_cls)
+        logger.info("Registering entity class: {}", name)
         # Probe with a no-root instance to check if paths are absolute.
         probe = entity_cls()
         static = probe.static_path
@@ -420,6 +437,7 @@ class AoI:
             entity_cls (type[BaseEntity]): The entity class to remove.
         """
         name = _entity_name(entity_cls)
+        logger.info("Deregistering entity class: {}", name)
         _REGISTRY.pop(name, None)
 
     @classmethod
@@ -452,11 +470,21 @@ def _validate_entity(entity: BaseEntity, name: str) -> None:
     try:
         static = entity._resolve(entity.static_path)
     except FileNotFoundError:
+        logger.error(
+            "Validation failed for entity {}: static_path '{}' does not exist.",
+            name,
+            entity.static_path,
+        )
         raise EntityValidationError(
             f"Entity {name!r}: static_path {entity.static_path!r} does not exist."
         )
 
     if not os.path.exists(static):
+        logger.error(
+            "Validation failed for entity {}: static path '{}' does not exist.",
+            name,
+            static,
+        )
         raise EntityValidationError(
             f"Entity {name!r}: static_path {static!r} does not exist."
         )
@@ -464,18 +492,34 @@ def _validate_entity(entity: BaseEntity, name: str) -> None:
     try:
         schema = pl.read_parquet_schema(static)
     except Exception as exc:
+        logger.error(
+            "Validation failed for entity {}: could not read schema from '{}': {}",
+            name,
+            static,
+            exc,
+        )
         raise EntityValidationError(
             f"Entity {name!r}: could not read schema from {static!r}: {exc}"
         ) from exc
 
     missing_keys = [c for c in entity.key_cols if c not in schema]
     if missing_keys:
+        logger.error(
+            "Validation failed for entity {}: key columns {} not found in schema.",
+            name,
+            missing_keys,
+        )
         raise EntityValidationError(
             f"Entity {name!r}: key_cols {missing_keys} not found in {static!r}. "
             f"Available columns: {list(schema.keys())}."
         )
 
     if entity.geometry_col not in schema:
+        logger.error(
+            "Validation failed for entity {}: geometry column '{}' not found in schema.",
+            name,
+            entity.geometry_col,
+        )
         raise EntityValidationError(
             f"Entity {name!r}: geometry_col {entity.geometry_col!r} "
             f"not found in {static!r}. Available columns: {list(schema.keys())}."
@@ -489,6 +533,12 @@ def _validate_entity(entity: BaseEntity, name: str) -> None:
             except FileNotFoundError:
                 abs_path = None
             if abs_path is None or not os.path.exists(abs_path):
+                logger.error(
+                    "Validation failed for entity {}: {} path '{}' does not exist.",
+                    name,
+                    label,
+                    path,
+                )
                 raise EntityValidationError(
                     f"Entity {name!r}: {label}_path {path!r} does not exist."
                 )

{core_lens-0.1.dev117 → core_lens-0.1.dev120}/src/core_lens/base/entity.py

@@ -16,6 +16,7 @@ from abc import ABC, abstractmethod
 from typing import TYPE_CHECKING, Any
 
 import polars as pl
+from loguru import logger
 
 from core_lens.utils.spatial import (
     bbox_intersects_geometry,
@@ -115,6 +116,9 @@ class BaseEntity(ABC):
             )
             p = root / p
         if not p.exists():
+            logger.error(
+                "Path resolution failed: '{}' (resolved to {}) does not exist.", path, p
+            )
             raise FileNotFoundError(
                 f"Entity path {path!r} (resolved to {p}) does not exist. "
                 "Provide an absolute path or ensure the file exists relative to "
@@ -219,6 +223,9 @@ class BaseEntity(ABC):
     @property
     def _index(self) -> pl.DataFrame:
         if not hasattr(self, "_cached_index"):
+            logger.debug(
+                "Building lazy bounding box index for {}", self.__class__.__name__
+            )
             profile = self.schema_profile
             self._cached_index: pl.DataFrame = build_bbox_index(
                 static_path=self._resolve(self.static_path),
@@ -256,6 +263,10 @@ class BaseEntity(ABC):
         from core_lens.aoi import _REGISTRY
         from core_lens.base.view import View
 
+        logger.debug(
+            "Applying attribute filters on {}: {}", self.__class__.__name__, kwargs
+        )
+
         static = self._resolve(self.static_path)
         schema = pl.read_parquet_schema(static)
 
@@ -265,6 +276,10 @@ class BaseEntity(ABC):
         # Validate entity-kwargs early so we give a useful error message.
         for k in entity_kwargs:
             if k not in _REGISTRY:
+                logger.error(
+                    "BaseEntity.where failed: '{}' is neither a column nor a registered entity.",
+                    k,
+                )
                 raise ValueError(
                     f"BaseEntity.where: {k!r} is not a column in {self.static_path!r} "
                     f"and is not a registered entity name. "
@@ -306,6 +321,12 @@ class BaseEntity(ABC):
             )
 
             if matched.is_empty():
+                logger.error(
+                    "BaseEntity.where failed: No rows matched {}={!r} in {}",
+                    entity_kwarg_name,
+                    entity_kwarg_val,
+                    other_entity.static_path,
+                )
                 raise ValueError(
                     f"BaseEntity.where: No rows matched {entity_kwarg_name}={entity_kwarg_val!r} "
                     f"in {other_entity.static_path!r}."
@@ -379,6 +400,9 @@ class BaseEntity(ABC):
         from core_lens.base.view import View
 
         if geometry is None and bbox is None:
+            logger.error(
+                "BaseEntity.spatial_filter failed: neither 'geometry' nor 'bbox' provided."
+            )
             raise ValueError(
                 "spatial_filter() requires either 'geometry' or 'bbox' to be provided."
             )
@@ -387,6 +411,12 @@ class BaseEntity(ABC):
 
         assert geometry is not None  # guaranteed by the guards above
 
+        logger.debug(
+            "Applying spatial filter on {} (relationship='{}')",
+            self.__class__.__name__,
+            relationship,
+        )
+
         profile = self.schema_profile
         candidates = bbox_intersects_geometry(self._index, geometry)
         keys = exact_spatial_filter(
@@ -424,6 +454,12 @@ class BaseEntity(ABC):
         """
         from core_lens.base.view import View
 
+        logger.debug(
+            "Deferred spatial join registered for {} with {}",
+            self.__class__.__name__,
+            other.__class__.__name__,
+        )
+
         entity_name = _entity_name(type(self))
         join_spec = {"other": other, "agg": agg}
         return View(

{core_lens-0.1.dev117 → core_lens-0.1.dev120}/src/core_lens/base/view.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Any
 
 import polars as pl
+from loguru import logger
 
 from enum import Enum
 
@@ -145,6 +146,9 @@ class View:
         )
 
         if geometry is None and bbox is None:
+            logger.error(
+                "View.spatial_filter failed: neither 'geometry' nor 'bbox' provided."
+            )
             raise ValueError(
                 "spatial_filter() requires either 'geometry' or 'bbox' to be provided."
             )
@@ -193,6 +197,9 @@ class View:
             View: A new lazy :class:`View` with the join spec recorded.
         """
         if self.join_spec is not None:
+            logger.error(
+                "View.spatial_join failed: View already has a pending spatial_join."
+            )
             raise ValueError("View already has a pending spatial_join.")
 
         return View(
@@ -252,23 +259,33 @@ class View:
                 supplying ``year`` with ``season="current"``).
         """
         if season is not None and (start is not None or end is not None):
+            logger.error(
+                "View.between failed: Date range (start/end) and season mode are mutually exclusive."
+            )
             raise ValueError(
                 "View.between: Date range (start/end) and season mode are mutually exclusive. "
                 "Use either positional date strings or the 'season' keyword, not both."
             )
 
         if season is None and year is not None:
+            logger.error(
+                "View.between failed: 'year' argument provided without 'season'."
+            )
             raise ValueError(
                 "View.between: 'year' argument is only valid when 'season' is also provided."
             )
 
         if season is not None:
             if not isinstance(season, Season):
+                logger.error("View.between failed: season is not a Season enum.")
                 raise ValueError(
                     f"View.between: season must be a Season enum. "
                     f"Valid options: {[e.name for e in Season]}."
                 )
             if season is Season.CURRENT and year is not None:
+                logger.error(
+                    "View.between failed: Cannot combine year with season='current'."
+                )
                 raise ValueError(
                     "View.between: Cannot combine year with season='current'. "
                     "The current season is always resolved to the present calendar date."
@@ -278,6 +295,9 @@ class View:
                 time_filter["year"] = year
         else:
             if start is None or end is None:
+                logger.error(
+                    "View.between failed: Both 'start' and 'end' must be provided for date range mode."
+                )
                 raise ValueError(
                     "View.between: Both 'start' and 'end' must be provided for date range mode."
                 )
@@ -340,12 +360,20 @@ class View:
 
         profile = self.entity.schema_profile
 
+        logger.info(
+            "Materialising {} resolution for {}", resolution.name, self.entity_name
+        )
+
         path: str
         if resolution == Resolution.STATIC:
             path = self.entity.static_path
         elif resolution == Resolution.ANNUAL:
             annual_path = self.entity.annual_path
             if annual_path is None:
+                logger.error(
+                    "View._materialise failed: Entity '{}' has no annual_path declared.",
+                    self.entity_name,
+                )
                 raise AttributeError(
                     f"Entity {self.entity_name!r} has no annual_path declared."
                 )
@@ -353,6 +381,10 @@ class View:
         else:
             fn_path = self.entity.fortnightly_path
             if fn_path is None:
+                logger.error(
+                    "View._materialise failed: Entity '{}' has no fortnightly_path declared.",
+                    self.entity_name,
+                )
                 raise AttributeError(
                     f"Entity {self.entity_name!r} has no fortnightly_path declared."
                 )
@@ -396,6 +428,7 @@ class View:
                 _tf = dict(self.time_filter)
                 if "start" in _tf and "end" in _tf:
                     _tf["_is_year_col"] = _is_year_col
+                logger.debug("Applying time filter expr using {}", _tf)
                 time_expr = resolve_time_filter(_tf, time_col, season_cfg)
 
         lf = scan_with_key_filter(
@@ -439,6 +472,7 @@ class View:
 
             from core_lens.utils.spatial import execute_spatial_join
 
+            logger.debug("Executing spatial join with {}", other_entity_name)
             data = execute_spatial_join(
                 primary_df=data,
                 primary_key_cols=self.entity.key_cols,

{core_lens-0.1.dev117 → core_lens-0.1.dev120}/src/core_lens/utils/spatial.py

@@ -7,6 +7,7 @@ from typing import TYPE_CHECKING, Any
 
 import polars as pl
 import shapely
+from loguru import logger
 
 if TYPE_CHECKING:
     pass
@@ -28,6 +29,9 @@ def resolve_path(path: str) -> str:
     if not p.is_absolute():
         p = pathlib.Path.cwd() / p
     if not p.exists():
+        logger.error(
+            "Path resolution failed: '{}' (resolved to {}) does not exist.", path, p
+        )
         raise FileNotFoundError(
             f"Entity path {path!r} (resolved to {p}) does not exist. "
             "Provide an absolute path or ensure the file exists relative to "
@@ -62,6 +66,7 @@ def build_bbox_index(
         pl.DataFrame: A ``pl.DataFrame`` with columns ``(*key_cols, minx, miny, maxx, maxy)``.
     """
     if bbox_cols is not None:
+        logger.debug("Using pre-computed bbox columns: {}", bbox_cols)
         cols_to_read = key_cols + list(bbox_cols)
         df = pl.read_parquet(static_path, columns=cols_to_read)
         minx_col, miny_col, maxx_col, maxy_col = bbox_cols
@@ -72,6 +77,9 @@ def build_bbox_index(
     cols_to_read = key_cols + [geometry_col]
     if geometry_type == "latlon":
         # For latlon, bbox_cols must be set — this path should not be reached.
+        logger.error(
+            "build_bbox_index failed: geometry_type='latlon' requires bbox_cols to be declared."
+        )
         raise ValueError(
             "geometry_type='latlon' requires bbox_cols to be declared on the entity. "
             + "Cannot compute bounds from separate lat/lon columns without bbox hints."
@@ -79,6 +87,11 @@ def build_bbox_index(
 
     import pyarrow.dataset as ds  # type: ignore[import-untyped]
 
+    logger.debug(
+        "No pre-computed bbox found in {}; falling back to Shapely decoding",
+        static_path,
+    )
+
     dataset = ds.dataset(static_path)
     chunks = []
 
@@ -184,7 +197,16 @@ def exact_spatial_filter(
     """
     import shapely
 
+    logger.debug(
+        "Refining {} candidates with exact spatial filter (relationship='{}')",
+        len(candidates),
+        relationship,
+    )
+
     if relationship not in ("centroid", "area"):
+        logger.error(
+            "exact_spatial_filter failed: Unknown relationship='{}'.", relationship
+        )
         raise ValueError(
             f"exact_spatial_filter: Unknown relationship={relationship!r}. "
             "Valid options: 'centroid', 'area'."
@@ -271,6 +293,10 @@ def execute_spatial_join(
     """
     import shapely
 
+    logger.info(
+        "Starting execute_spatial_join for other_entity_name={}", other_entity_name
+    )
+
     other_profile = other_entity.schema_profile
     other_static = other_entity._resolve(other_entity.static_path)
     other_geom_col = other_profile.geometry_col
@@ -304,6 +330,10 @@ def execute_spatial_join(
 
     # Decode primary geometries.
     if primary_geom_col not in primary_df.columns:
+        logger.error(
+            "execute_spatial_join failed: geometry column '{}' not found in primary DataFrame.",
+            primary_geom_col,
+        )
         raise ValueError(
             f"execute_spatial_join: geometry column {primary_geom_col!r} not found "
             "in primary DataFrame.  Materialise static resolution or call "

{core_lens-0.1.dev117 → core_lens-0.1.dev120}/tests/unit/test_entity.py

@@ -48,9 +48,17 @@ class TestEntityWhere:
         ).write_parquet(district_path)
 
         class CustomDistrictEntity(BaseEntity):
-            key_cols = ["district_id"]
-            geometry_col = "geometry"
-            static_path = str(district_path)
+            @property
+            def key_cols(self) -> list[str]:
+                return ["district_id"]
+
+            @property
+            def geometry_col(self) -> str:
+                return "geometry"
+
+            @property
+            def static_path(self) -> str:
+                return str(district_path)
 
             @property
             def schema_profile(self) -> Any: