core-lens 0.1.dev169__tar.gz → 0.1.dev171__tar.gz

{core_lens-0.1.dev169 → core_lens-0.1.dev171}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: core-lens
-Version: 0.1.dev169
+Version: 0.1.dev171
 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

{core_lens-0.1.dev169 → core_lens-0.1.dev171}/docs/source/queries.md

@@ -54,10 +54,10 @@ joined_view = aoi.mws.spatial_join(
     }
 )
 
-# Materialise (Note: spatial join materialisation raises NotImplementedError in this release)
-# res = joined_view.annual
+# Materialise the joined view
+res = joined_view.annual
 ```
 
 ```{note}
-Cross-entity spatial join execution (materialisation) is currently under development and will be added in a subsequent release. Calling materialisation methods (like `.annual`, `.static`, or `.sub_annual`) on a joined view will raise a `NotImplementedError` in the current version.
+Cross-entity spatial join execution (materialisation) is fully supported. Calling materialisation methods (like `.annual`, `.static`, or `.sub_annual`) on a joined view will evaluate the deferred join and execute it.
 ```

{core_lens-0.1.dev169 → core_lens-0.1.dev171}/pyproject.toml

@@ -139,3 +139,6 @@ ignore = [
 [tool.ruff.lint.per-file-ignores]
 "tests/*" = ["S"]
 "examples/*" = ["S"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"

{core_lens-0.1.dev169 → core_lens-0.1.dev171}/src/core_lens/__init__.py

@@ -1,3 +1,5 @@
+"""Core Lens package."""
+
 try:
     from ._version import __version__
 except ImportError:

{core_lens-0.1.dev169 → core_lens-0.1.dev171}/src/core_lens/__main__.py

@@ -1,7 +1,14 @@
+"""Module for Core Lens."""
+
 from . import __version__
 
 
 def hello() -> str:
+    """Return hello message.
+
+    Returns:
+        A welcome string describing core-lens capabilities.
+    """
     hello_str = """Hello from core-lens!
 
 The following primary capabilities are available:
@@ -28,6 +35,11 @@ Visualisation (via `result.plot`):
 
 
 def version() -> str:
+    """Return version string.
+
+    Returns:
+        The current core-lens package version.
+    """
     return str(__version__)
 
 

{core_lens-0.1.dev169 → core_lens-0.1.dev171}/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.dev169'
-__version_tuple__ = version_tuple = (0, 1, 'dev169')
+__version__ = version = '0.1.dev171'
+__version_tuple__ = version_tuple = (0, 1, 'dev171')
 
 __commit_id__ = commit_id = None

{core_lens-0.1.dev169 → core_lens-0.1.dev171}/src/core_lens/aoi.py

@@ -56,6 +56,13 @@ class SeasonConfig:
     zaid: tuple[str, str] = ("04-01", "06-30")
 
     def __post_init__(self) -> None:
+        """Initialize after dataclass creation.
+
+        Validates that all configured seasons have valid MM-DD ranges.
+
+        Raises:
+            ValueError: If a season date format is invalid.
+        """
         from datetime import datetime
 
         for attr in ("kharif", "rabi", "zaid"):
@@ -151,7 +158,7 @@ def _cached_resolve_boundary(
     storage_options_key: tuple[tuple[str, Any], ...],
     entity_kwargs_key: tuple[tuple[str, Any], ...],
 ) -> tuple[bytes, str, tuple[tuple[Any, ...], ...]]:
-    """Cached boundary resolution: return ``(geometry_wkb, entity_name, key_rows)``.
+    """Return cached boundary resolution: ``(geometry_wkb, entity_name, key_rows)``.
 
     All arguments must be hashable.  ``entity_kwargs`` must be converted to a
     sorted tuple of ``(key, value)`` pairs before calling this function.
@@ -542,6 +549,19 @@ class AoI:
             self._get_entity(name)
 
     def __getattr__(self, name: str) -> "View":
+        """Get view by entity name.
+
+        Resolves and caches a scoped view for a registered entity on first access.
+
+        Args:
+            name: The registered entity name (e.g. 'mws').
+
+        Returns:
+            The scoped View for the entity.
+
+        Raises:
+            AttributeError: If the entity is not registered.
+        """
         # Called only when normal attribute lookup has already failed, so this
         # never shadows real attributes.  Maps entity names to their scoped Views.
         if name in _REGISTRY:

{core_lens-0.1.dev169 → core_lens-0.1.dev171}/src/core_lens/base/entity.py

@@ -80,7 +80,7 @@ def _cached_detect(
     sub_annual_path: str | None,
     storage_options_key: tuple[tuple[str, Any], ...],
 ) -> "SchemaProfile":
-    """Cached wrapper around :func:`~core_lens.schema.detection.detect`.
+    """Wrap :func:`~core_lens.schema.detection.detect` with caching.
 
     All arguments must be hashable so they can form the cache key.  Pass
     ``storage_options`` through :func:`_so_key` before calling this function.
@@ -110,7 +110,7 @@ def _cached_build_index(
     geometry_type: str,
     storage_options_key: tuple[tuple[str, Any], ...],
 ) -> pl.DataFrame:
-    """Cached wrapper around :func:`~core_lens.utils.spatial.build_bbox_index`.
+    """Wrap :func:`~core_lens.utils.spatial.build_bbox_index` with caching.
 
     All arguments must be hashable so they can form the cache key.  Pass
     ``storage_options`` through :func:`_so_key` before calling this function.

{core_lens-0.1.dev169 → core_lens-0.1.dev171}/src/core_lens/base/namespaces/__init__.py

@@ -1,3 +1,5 @@
+"""Core Lens package."""
+
 __module__: str = "core_lens.base.namespaces"
 
 from core_lens.base.namespaces.plot import PlotNamespace

{core_lens-0.1.dev169 → core_lens-0.1.dev171}/src/core_lens/base/namespaces/plot.py

@@ -231,6 +231,17 @@ class MapWithLegend:
         clamped_min: bool = False,
         clamped_max: bool = False,
     ) -> None:
+        """Initialize MapWithLegend.
+
+        Args:
+            map_widget: The underlying Lonboard map instance.
+            cmap: The colormap applied to the map.
+            v_min: Minimum value of the color scale.
+            v_max: Maximum value of the color scale.
+            column_name: Name of the visualized column.
+            clamped_min: True if values below v_min were clamped.
+            clamped_max: True if values above v_max were clamped.
+        """
         self._map = map_widget
         self._cmap = cmap
         self._v_min = v_min
@@ -240,6 +251,14 @@ class MapWithLegend:
         self._clamped_max = clamped_max
 
     def __getattr__(self, name: str) -> Any:
+        """Get map attribute.
+
+        Args:
+            name: The attribute name to look up on the underlying map.
+
+        Returns:
+            The requested attribute from the map widget.
+        """
         return getattr(self._map, name)
 
     def _generate_legend_div(self, absolute: bool = True) -> str:
@@ -336,6 +355,11 @@ class PlotNamespace:
     """
 
     def __init__(self, result: "Result") -> None:
+        """Initialize PlotNamespace.
+
+        Args:
+            result: The parent Result object this namespace is bound to.
+        """
         self.result = result
 
     def choropleth(
@@ -355,6 +379,8 @@ class PlotNamespace:
             subplot_on (SubplotOn | None, optional): Optional temporal dimension to split data across.
                 A :class:`~core_lens.base.namespaces.plot.SubplotOn` enum value. When set, one layer is rendered per unique
                 value of ``subplot_on`` in the data.
+            v_min (float | None, optional): Minimum value for color scale.
+            v_max (float | None, optional): Maximum value for color scale.
 
         Returns:
             lonboard.Map: A Lonboard Map object.

{core_lens-0.1.dev169 → core_lens-0.1.dev171}/src/core_lens/base/namespaces/stats.py

@@ -158,6 +158,11 @@ class StatsNamespace:
     """
 
     def __init__(self, result: "Result") -> None:
+        """Initialize StatsNamespace.
+
+        Args:
+            result: The parent Result object this namespace is bound to.
+        """
         self._r = result
 
     def _numeric_cols(self, df: pl.DataFrame) -> list[str]:

{core_lens-0.1.dev169 → core_lens-0.1.dev171}/src/core_lens/base/result.py

@@ -67,6 +67,17 @@ class Result:
         entity: "BaseEntity",
         metadata: dict[str, Any] | None = None,
     ) -> None:
+        """Initialize Result.
+
+        Args:
+            data: The underlying dataframe or lazyframe.
+            resolution: The spatial and temporal resolution of the data.
+            has_geometry: True if the geometry column is populated.
+            key_cols: Primary key columns linking back to the entity.
+            entity_name: Registered name of the parent entity.
+            entity: The BaseEntity object that produced this result.
+            metadata: Additional metadata dictionary to store.
+        """
         self.data = data.lazy() if isinstance(data, pl.DataFrame) else data
         self.resolution = resolution
         self.has_geometry = has_geometry
@@ -94,6 +105,7 @@ class Result:
 
         Returns:
             Result: A new Result with the data cached as an in-memory LazyFrame.
+
         """
         return self._replace(data=self.df().lazy())
 

{core_lens-0.1.dev169 → core_lens-0.1.dev171}/src/core_lens/base/view.py

@@ -24,6 +24,11 @@ if TYPE_CHECKING:
 
 
 class Season(Enum):
+    """Season enum.
+
+    Enumerates standard agronomic seasons used across Core Lens for temporal filtering.
+    """
+
     KHARIF = "kharif"
     RABI = "rabi"
     ZAID = "zaid"
@@ -78,6 +83,16 @@ class View:
         join_spec: dict[str, Any] | None = None,
         season_config: SeasonConfig | None = None,
     ) -> None:
+        """Initialize View.
+
+        Args:
+            keys: Polars LazyFrame or DataFrame containing the resolved IDs.
+            entity: Parent BaseEntity instance defining the schema and paths.
+            entity_name: Registered string name of the entity.
+            time_filter: Active time filter conditions, if any.
+            join_spec: Active spatial join spec, if any.
+            season_config: Optional season date configuration overrides.
+        """
         self.keys = keys.lazy() if isinstance(keys, pl.DataFrame) else keys
         self.entity = entity
         self.entity_name = entity_name

{core_lens-0.1.dev169 → core_lens-0.1.dev171}/src/core_lens/entities/__init__.py

@@ -1,3 +1,5 @@
+"""Core Lens package."""
+
 __module__: str = "core_lens.entities"
 
 from core_lens.entities.tehsil import TehsilEntity

{core_lens-0.1.dev169 → core_lens-0.1.dev171}/src/core_lens/entities/mws.py

@@ -1,3 +1,5 @@
+"""Module for Core Lens."""
+
 from core_lens.base.entity import BaseEntity
 
 

{core_lens-0.1.dev169 → core_lens-0.1.dev171}/src/core_lens/entities/tehsil.py

@@ -1,3 +1,5 @@
+"""Module for Core Lens."""
+
 from core_lens.base.entity import BaseEntity
 from core_lens.schema.profile import SchemaProfile
 

{core_lens-0.1.dev169 → core_lens-0.1.dev171}/src/core_lens/entities/waterbody.py

@@ -1,3 +1,5 @@
+"""Module for Core Lens."""
+
 from core_lens.base.entity import BaseEntity
 
 

{core_lens-0.1.dev169 → core_lens-0.1.dev171}/src/core_lens/export/__init__.py

@@ -1,3 +1,5 @@
+"""Core Lens package."""
+
 __module__: str = "core_lens.export"
 
 from core_lens.export.formats import csv, geojson, geoparquet, json, parquet

{core_lens-0.1.dev169 → core_lens-0.1.dev171}/src/core_lens/export/formats.py

@@ -1,3 +1,5 @@
+"""Module for Core Lens."""
+
 import pathlib
 from typing import TYPE_CHECKING, Any
 
@@ -166,17 +168,14 @@ def geoparquet(result: "Result", path: str | pathlib.Path, **kwargs: Any) -> Non
 def geojson(result: "Result", path: str | pathlib.Path, **kwargs: Any) -> None:
     """Export the result data to a GeoJSON file.
 
-    This function uses GeoPandas to write the data frame.  It prefers the
-    ``pyogrio`` engine (faster, C-backed) when available and falls back to
-    ``fiona`` automatically.  The ``engine`` kwarg can override this:
-    ``engine="fiona"`` or ``engine="pyogrio"``.
+    This function natively streams the data directly from Polars and Shapely
+    without invoking GDAL or DuckDB, making it fast for large datasets.
 
     Args:
         result (Result): The Result object to export.
         path (str | pathlib.Path): Destination path for the GeoJSON file.
-        **kwargs (Any): Additional options forwarded to
-            ``GeoDataFrame.to_file()`` (e.g. ``driver="GeoJSON"``,
-            ``engine="pyogrio"``).
+        **kwargs (Any): Driver-specific kwargs are currently ignored.
+            The `driver` keyword argument supports `GeoJSONSeq` for newline-delimited GeoJSON.
 
     Example:
         >>> from core_lens.export import geojson

{core_lens-0.1.dev169 → core_lens-0.1.dev171}/src/core_lens/utils/__init__.py

@@ -1 +1,3 @@
+"""Core Lens package."""
+
 __module__: str = "core_lens.utils"

{core_lens-0.1.dev169 → core_lens-0.1.dev171}/src/core_lens/utils/polars_utils.py

@@ -22,7 +22,7 @@ def _cached_schema_internal(path: str, so_key: tuple[tuple[str, Any], ...]) -> A
 
 
 def cached_read_schema(path: str, storage_options: dict[str, Any] | None = None) -> Any:
-    """Cached wrapper around pl.read_parquet_schema.
+    """Wrap pl.read_parquet_schema with caching.
 
     Avoids repeated Parquet footer reads for schema resolution in hot paths.
     """