agrigee-lite-client 3.4.1__py3-none-any.whl

agrigee_lite_client/__init__.py

@@ -0,0 +1,25 @@
+"""Thin HTTP client for the AgriGEE.lite REST API. See SPECS.md."""
+
+from agrigee_lite_client._async_client import AsyncAgriGEEClient
+from agrigee_lite_client._client import AgriGEEClient
+from agrigee_lite_client._exceptions import (
+    AgriGEEClientError,
+    AgriGEEHTTPError,
+    AgriGEEJobError,
+    AgriGEEJobTimeoutError,
+    AgriGEEUnknownSatelliteError,
+    AgriGEEVersionMismatchError,
+)
+from agrigee_lite_client._version import __version__
+
+__all__ = [
+    "AgriGEEClient",
+    "AgriGEEClientError",
+    "AgriGEEHTTPError",
+    "AgriGEEJobError",
+    "AgriGEEJobTimeoutError",
+    "AgriGEEUnknownSatelliteError",
+    "AgriGEEVersionMismatchError",
+    "AsyncAgriGEEClient",
+    "__version__",
+]

agrigee_lite_client/_async_client.py

@@ -0,0 +1,205 @@
+"""Asynchronous AsyncAgriGEEClient — mirrors _client.py. See SPECS.md §4.
+
+Deliberately duplicated rather than unified with the sync client (see
+SPECS.md §4): only the I/O (httpx calls, sleep) differs, and ``_get.py``
+already carries every bit of logic that's actually shared.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import zipfile
+from typing import Any
+
+import httpx
+import polars as pl
+from shapely.geometry.base import BaseGeometry
+
+from agrigee_lite_client import _geo_compat, _get, _satellite_dates, _validation
+from agrigee_lite_client._client import _raise_for_status
+from agrigee_lite_client._exceptions import AgriGEEJobError, AgriGEEJobTimeoutError, AgriGEEVersionMismatchError
+from agrigee_lite_client._version import __version__
+
+
+class _AsyncGet:
+    """Bound to a single ``AsyncAgriGEEClient`` — mirrors ``agl.get.*``."""
+
+    def __init__(self, client: AsyncAgriGEEClient) -> None:
+        self._client = client
+
+    async def sits(
+        self,
+        geometry: BaseGeometry,
+        start_date: str,
+        end_date: str,
+        satellite: str,
+        satellite_params: dict[str, Any] | None = None,
+        reducers: list[str] | None = None,
+        subsampling_max_pixels: float = 1_000,
+    ) -> pl.DataFrame:
+        """Naive: wraps a 1-row frame and calls ``multiple_sits`` (SPECS.md §6)."""
+        frame = _get.build_single_sits_frame(geometry, start_date, end_date)
+        return await self.multiple_sits(
+            frame,
+            satellite=satellite,
+            satellite_params=satellite_params,
+            reducers=reducers,
+            subsampling_max_pixels=subsampling_max_pixels,
+        )
+
+    async def multiple_sits(
+        self,
+        gdf,
+        satellite: str,
+        satellite_params: dict[str, Any] | None = None,
+        reducers: list[str] | None = None,
+        start_date_column: str = "start_date",
+        end_date_column: str = "end_date",
+        original_index_column: str = "original_index",
+        subsampling_max_pixels: float = 1_000,
+        chunksize: int = 10,
+        max_parallel_downloads: int = 40,
+        max_retries_per_chunk: int = 8,
+        force_redownload: bool = False,
+    ) -> pl.DataFrame:
+        await self._client._ensure_server_version_matches()
+
+        frame = _geo_compat.to_wkb_frame(gdf)
+        satellite_start, satellite_end = _satellite_dates.get_satellite_date_range(satellite, satellite_params)
+        validated = _validation.drop_rows_outside_satellite_range(
+            frame,
+            satellite_start=satellite_start,
+            satellite_end=satellite_end,
+            start_date_column=start_date_column,
+            end_date_column=end_date_column,
+        )
+
+        parquet_bytes, form = _get.build_multiple_sits_upload(
+            validated,
+            satellite=satellite,
+            satellite_params=satellite_params,
+            reducers=reducers,
+            start_date_column=start_date_column,
+            end_date_column=end_date_column,
+            original_index_column=original_index_column,
+            subsampling_max_pixels=subsampling_max_pixels,
+            chunksize=chunksize,
+            max_parallel_downloads=max_parallel_downloads,
+            max_retries_per_chunk=max_retries_per_chunk,
+            force_redownload=force_redownload,
+        )
+        response = await self._client._http.post(
+            "/sits/multiple/file",
+            files={"file": ("geometries.parquet", parquet_bytes, "application/octet-stream")},
+            data=form,
+        )
+        _raise_for_status(response)
+        job_id = response.json()["id"]
+        await self._client._wait_for_job(job_id)
+        content = await self._client._download_job(job_id)
+        return _get.parse_sits_download(content)
+
+    async def image(
+        self,
+        geometry: BaseGeometry,
+        start_date: str,
+        end_date: str,
+        satellite: str,
+        satellite_params: dict[str, Any] | None = None,
+        invalid_images_threshold: float = 0.5,
+        max_parallel_downloads: int = 40,
+        force_redownload: bool = False,
+        image_indices: list[int] | None = None,
+        scale: float | None = None,
+        dimensions: int | str | None = None,
+    ) -> zipfile.ZipFile:
+        body = _get.build_images_request(
+            geometry,
+            start_date=start_date,
+            end_date=end_date,
+            satellite=satellite,
+            satellite_params=satellite_params,
+            invalid_images_threshold=invalid_images_threshold,
+            max_parallel_downloads=max_parallel_downloads,
+            force_redownload=force_redownload,
+            image_indices=image_indices,
+            scale=scale,
+            dimensions=dimensions,
+        )
+        response = await self._client._http.post("/images", json=body)
+        _raise_for_status(response)
+        job_id = response.json()["id"]
+        await self._client._wait_for_job(job_id)
+        content = await self._client._download_job(job_id)
+        return _get.parse_image_download(content)
+
+
+class AsyncAgriGEEClient:
+    """Asynchronous client for the AgriGEE.lite REST API. See SPECS.md."""
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        timeout: float = 60.0,
+        poll_interval: float = 1.0,
+        poll_timeout: float | None = None,
+    ) -> None:
+        self._http = httpx.AsyncClient(base_url=base_url, timeout=timeout)
+        self._poll_interval = poll_interval
+        self._poll_timeout = poll_timeout
+        self._version_checked = False
+        self.get = _AsyncGet(self)
+
+    async def __aenter__(self) -> AsyncAgriGEEClient:
+        return self
+
+    async def __aexit__(self, *exc_info: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def health(self) -> bool:
+        response = await self._http.get("/health")
+        _raise_for_status(response)
+        return response.json().get("status") == "ok"
+
+    async def list_satellites(self) -> list[str]:
+        response = await self._http.get("/satellites")
+        _raise_for_status(response)
+        return response.json()
+
+    async def _ensure_server_version_matches(self) -> None:
+        """Checked once per instance, before trusting the embedded satellite
+        date table (_satellite_dates.py) — see AgriGEEVersionMismatchError.
+        """
+        if self._version_checked:
+            return
+        response = await self._http.get("/version")
+        _raise_for_status(response)
+        server_version = response.json().get("version")
+        if server_version != __version__:
+            raise AgriGEEVersionMismatchError(__version__, server_version)
+        self._version_checked = True
+
+    async def _wait_for_job(self, job_id: str) -> None:
+        elapsed = 0.0
+        while True:
+            response = await self._http.get(f"/jobs/{job_id}")
+            _raise_for_status(response)
+            job = response.json()
+            status = job["status"]
+            if status == "completed":
+                return
+            if status == "failed":
+                raise AgriGEEJobError(job_id, job.get("error"))
+            if self._poll_timeout is not None and elapsed >= self._poll_timeout:
+                raise AgriGEEJobTimeoutError(job_id, self._poll_timeout)
+            await asyncio.sleep(self._poll_interval)
+            elapsed += self._poll_interval
+
+    async def _download_job(self, job_id: str) -> bytes:
+        response = await self._http.get(f"/jobs/{job_id}/download")
+        _raise_for_status(response)
+        return response.content

agrigee_lite_client/_client.py

@@ -0,0 +1,213 @@
+"""Synchronous AgriGEEClient. See SPECS.md §4 and §6."""
+
+from __future__ import annotations
+
+import contextlib
+import time
+import zipfile
+from typing import Any
+
+import httpx
+import polars as pl
+from shapely.geometry.base import BaseGeometry
+
+from agrigee_lite_client import _geo_compat, _get, _satellite_dates, _validation
+from agrigee_lite_client._exceptions import (
+    AgriGEEHTTPError,
+    AgriGEEJobError,
+    AgriGEEJobTimeoutError,
+    AgriGEEVersionMismatchError,
+)
+from agrigee_lite_client._version import __version__
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    if response.is_error:
+        detail = response.text
+        with contextlib.suppress(Exception):
+            detail = response.json().get("detail", detail)
+        raise AgriGEEHTTPError(response.status_code, detail)
+
+
+class _SyncGet:
+    """Bound to a single ``AgriGEEClient`` — mirrors ``agl.get.*``."""
+
+    def __init__(self, client: AgriGEEClient) -> None:
+        self._client = client
+
+    def sits(
+        self,
+        geometry: BaseGeometry,
+        start_date: str,
+        end_date: str,
+        satellite: str,
+        satellite_params: dict[str, Any] | None = None,
+        reducers: list[str] | None = None,
+        subsampling_max_pixels: float = 1_000,
+    ) -> pl.DataFrame:
+        """Naive: wraps a 1-row frame and calls ``multiple_sits`` (SPECS.md §6)."""
+        frame = _get.build_single_sits_frame(geometry, start_date, end_date)
+        return self.multiple_sits(
+            frame,
+            satellite=satellite,
+            satellite_params=satellite_params,
+            reducers=reducers,
+            subsampling_max_pixels=subsampling_max_pixels,
+        )
+
+    def multiple_sits(
+        self,
+        gdf,
+        satellite: str,
+        satellite_params: dict[str, Any] | None = None,
+        reducers: list[str] | None = None,
+        start_date_column: str = "start_date",
+        end_date_column: str = "end_date",
+        original_index_column: str = "original_index",
+        subsampling_max_pixels: float = 1_000,
+        chunksize: int = 10,
+        max_parallel_downloads: int = 40,
+        max_retries_per_chunk: int = 8,
+        force_redownload: bool = False,
+    ) -> pl.DataFrame:
+        self._client._ensure_server_version_matches()
+
+        frame = _geo_compat.to_wkb_frame(gdf)
+        satellite_start, satellite_end = _satellite_dates.get_satellite_date_range(satellite, satellite_params)
+        validated = _validation.drop_rows_outside_satellite_range(
+            frame,
+            satellite_start=satellite_start,
+            satellite_end=satellite_end,
+            start_date_column=start_date_column,
+            end_date_column=end_date_column,
+        )
+
+        parquet_bytes, form = _get.build_multiple_sits_upload(
+            validated,
+            satellite=satellite,
+            satellite_params=satellite_params,
+            reducers=reducers,
+            start_date_column=start_date_column,
+            end_date_column=end_date_column,
+            original_index_column=original_index_column,
+            subsampling_max_pixels=subsampling_max_pixels,
+            chunksize=chunksize,
+            max_parallel_downloads=max_parallel_downloads,
+            max_retries_per_chunk=max_retries_per_chunk,
+            force_redownload=force_redownload,
+        )
+        response = self._client._http.post(
+            "/sits/multiple/file",
+            files={"file": ("geometries.parquet", parquet_bytes, "application/octet-stream")},
+            data=form,
+        )
+        _raise_for_status(response)
+        job_id = response.json()["id"]
+        self._client._wait_for_job(job_id)
+        content = self._client._download_job(job_id)
+        return _get.parse_sits_download(content)
+
+    def image(
+        self,
+        geometry: BaseGeometry,
+        start_date: str,
+        end_date: str,
+        satellite: str,
+        satellite_params: dict[str, Any] | None = None,
+        invalid_images_threshold: float = 0.5,
+        max_parallel_downloads: int = 40,
+        force_redownload: bool = False,
+        image_indices: list[int] | None = None,
+        scale: float | None = None,
+        dimensions: int | str | None = None,
+    ) -> zipfile.ZipFile:
+        body = _get.build_images_request(
+            geometry,
+            start_date=start_date,
+            end_date=end_date,
+            satellite=satellite,
+            satellite_params=satellite_params,
+            invalid_images_threshold=invalid_images_threshold,
+            max_parallel_downloads=max_parallel_downloads,
+            force_redownload=force_redownload,
+            image_indices=image_indices,
+            scale=scale,
+            dimensions=dimensions,
+        )
+        response = self._client._http.post("/images", json=body)
+        _raise_for_status(response)
+        job_id = response.json()["id"]
+        self._client._wait_for_job(job_id)
+        content = self._client._download_job(job_id)
+        return _get.parse_image_download(content)
+
+
+class AgriGEEClient:
+    """Synchronous client for the AgriGEE.lite REST API. See SPECS.md."""
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        timeout: float = 60.0,
+        poll_interval: float = 1.0,
+        poll_timeout: float | None = None,
+    ) -> None:
+        self._http = httpx.Client(base_url=base_url, timeout=timeout)
+        self._poll_interval = poll_interval
+        self._poll_timeout = poll_timeout
+        self._version_checked = False
+        self.get = _SyncGet(self)
+
+    def __enter__(self) -> AgriGEEClient:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def health(self) -> bool:
+        response = self._http.get("/health")
+        _raise_for_status(response)
+        return response.json().get("status") == "ok"
+
+    def list_satellites(self) -> list[str]:
+        response = self._http.get("/satellites")
+        _raise_for_status(response)
+        return response.json()
+
+    def _ensure_server_version_matches(self) -> None:
+        """Checked once per instance, before trusting the embedded satellite
+        date table (_satellite_dates.py) — see AgriGEEVersionMismatchError.
+        """
+        if self._version_checked:
+            return
+        response = self._http.get("/version")
+        _raise_for_status(response)
+        server_version = response.json().get("version")
+        if server_version != __version__:
+            raise AgriGEEVersionMismatchError(__version__, server_version)
+        self._version_checked = True
+
+    def _wait_for_job(self, job_id: str) -> None:
+        elapsed = 0.0
+        while True:
+            response = self._http.get(f"/jobs/{job_id}")
+            _raise_for_status(response)
+            job = response.json()
+            status = job["status"]
+            if status == "completed":
+                return
+            if status == "failed":
+                raise AgriGEEJobError(job_id, job.get("error"))
+            if self._poll_timeout is not None and elapsed >= self._poll_timeout:
+                raise AgriGEEJobTimeoutError(job_id, self._poll_timeout)
+            time.sleep(self._poll_interval)
+            elapsed += self._poll_interval
+
+    def _download_job(self, job_id: str) -> bytes:
+        response = self._http.get(f"/jobs/{job_id}/download")
+        _raise_for_status(response)
+        return response.content

agrigee_lite_client/_exceptions.py

@@ -0,0 +1,57 @@
+"""Exception hierarchy for agrigee_lite_client. See SPECS.md §7."""
+
+from __future__ import annotations
+
+
+class AgriGEEClientError(Exception):
+    """Base class for every error this client raises."""
+
+
+class AgriGEEHTTPError(AgriGEEClientError):
+    """The server returned an HTTP error status."""
+
+    def __init__(self, status_code: int, detail: str) -> None:
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(f"HTTP {status_code}: {detail}")
+
+
+class AgriGEEJobError(AgriGEEClientError):
+    """A submitted job finished with status='failed'."""
+
+    def __init__(self, job_id: str, error: str | None) -> None:
+        self.job_id = job_id
+        self.error = error
+        super().__init__(f"Job {job_id} failed: {error}")
+
+
+class AgriGEEJobTimeoutError(AgriGEEClientError):
+    """poll_timeout elapsed before the job reached a terminal status."""
+
+    def __init__(self, job_id: str, poll_timeout: float) -> None:
+        self.job_id = job_id
+        self.poll_timeout = poll_timeout
+        super().__init__(f"Job {job_id} did not finish within {poll_timeout}s")
+
+
+class AgriGEEVersionMismatchError(AgriGEEClientError):
+    """The server's agrigee_lite version doesn't match this client's.
+
+    Raised before trusting the client's embedded satellite date table
+    (SPECS.md §5.5) — that table is a static copy of server-side data, only
+    guaranteed correct when both sides are on the same version.
+    """
+
+    def __init__(self, client_version: str, server_version: str | None) -> None:
+        self.client_version = client_version
+        self.server_version = server_version
+        reported = server_version if server_version is not None else "an unknown version (no 'version' in /version)"
+        super().__init__(
+            f"agrigee_lite_client is version {client_version} but the server is running {reported}. "
+            "Install matching versions of both — the client's satellite date table is only valid "
+            "when they agree."
+        )
+
+
+class AgriGEEUnknownSatelliteError(AgriGEEClientError):
+    """A satellite name isn't in this client's embedded date-range table."""

agrigee_lite_client/_geo_compat.py

@@ -0,0 +1,47 @@
+"""Accepts geopolars.GeoDataFrame, plain polars.DataFrame, or (if installed)
+geopandas.GeoDataFrame as input to multiple_sits — geopandas is never a hard
+dependency of this package (SPECS.md §3): it's detected lazily via
+try/except ImportError, and only actually touched if the caller passes one.
+
+geopolars.GeoDataFrame and plain polars.DataFrame already store their
+geometry column as WKB Binary (verified against geopolars 0.1.0-alpha.4 —
+see _geoparquet.py's module docstring), so both go straight to
+build_geoparquet_bytes unchanged; only geopandas input needs converting.
+"""
+
+from __future__ import annotations
+
+import polars as pl
+
+
+def _is_geopandas_geodataframe(frame: object) -> bool:
+    try:
+        import geopandas as gpd
+    except ImportError:
+        return False
+    return isinstance(frame, gpd.GeoDataFrame)
+
+
+def _check_geopandas_crs_is_wgs84(frame) -> None:
+    if frame.crs is not None and frame.crs != "EPSG:4326":
+        msg = (
+            f"Geometry CRS is {frame.crs!r}, but agrigee_lite_client never reprojects "
+            "(SPECS.md §1) — reproject to EPSG:4326 yourself before calling multiple_sits/sits, "
+            "e.g. `gdf.to_crs('EPSG:4326')`."
+        )
+        raise ValueError(msg)
+
+
+def to_wkb_frame(frame, *, geometry_column: str = "geometry") -> pl.DataFrame:
+    """Normalize any accepted frame type to a plain polars.DataFrame whose
+    ``geometry_column`` holds WKB bytes, ready for build_geoparquet_bytes.
+    """
+    if _is_geopandas_geodataframe(frame):
+        import shapely
+
+        _check_geopandas_crs_is_wgs84(frame)
+        wkb = shapely.to_wkb(frame[geometry_column].to_numpy())
+        rest = pl.from_pandas(frame.drop(columns=[geometry_column]))
+        return rest.with_columns(pl.Series(geometry_column, wkb))
+
+    return frame

agrigee_lite_client/_geoparquet.py

@@ -0,0 +1,66 @@
+"""GeoParquet encoding/decoding without geopandas. See SPECS.md §5.1.
+
+geopolars 0.1.0-alpha.4 does not write GeoParquet file metadata on its own:
+``GeoDataFrame.write_parquet`` is the plain ``polars.DataFrame.write_parquet``
+(inherited, not overridden), and a geometry column round-trips through Arrow
+as a bare ``Binary`` array with no CRS or extension type attached. The server
+decodes uploads with ``geopandas.read_parquet``, which looks for a ``"geo"``
+key in the Parquet file-level metadata
+(https://geoparquet.org/releases/v1.0.0/), so this module builds that key by
+hand — verified end-to-end against ``geopandas.read_parquet`` in
+``tests/test_geoparquet.py``.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+from collections.abc import Iterable
+
+import polars as pl
+import pyarrow.parquet as pq
+import shapely
+from shapely.geometry.base import BaseGeometry
+
+_GEOPARQUET_VERSION = "1.0.0"
+
+
+def _geo_metadata(primary_column: str) -> bytes:
+    return json.dumps(
+        {
+            "version": _GEOPARQUET_VERSION,
+            "primary_column": primary_column,
+            "columns": {
+                # geometry_types=[] is valid per spec ("not specified") — this
+                # client never introspects per-row geometry types.
+                # crs is decorative here: the server takes the authoritative
+                # CRS from the `crs` multipart form field, not this metadata
+                # (see SPECS.md §5.1). Geometries must already be WGS84.
+                primary_column: {"encoding": "WKB", "geometry_types": [], "crs": "OGC:CRS84"},
+            },
+        }
+    ).encode()
+
+
+def encode_geometries(geometries: Iterable[BaseGeometry]) -> list[bytes]:
+    """Serialize shapely geometries to WKB bytes for a Binary parquet column."""
+    return [shapely.to_wkb(geometry) for geometry in geometries]
+
+
+def build_geoparquet_bytes(frame, *, geometry_column: str = "geometry") -> bytes:
+    """Serialize a geopolars.GeoDataFrame or polars.DataFrame to GeoParquet bytes.
+
+    ``geometry_column`` must already hold WKB bytes (``polars.Binary``) —
+    build it with ``encode_geometries`` first.
+    """
+    table = frame.to_arrow()
+    existing_metadata = table.schema.metadata or {}
+    table = table.replace_schema_metadata({**existing_metadata, b"geo": _geo_metadata(geometry_column)})
+    buf = io.BytesIO()
+    pq.write_table(table, buf)
+    return buf.getvalue()
+
+
+def read_plain_parquet_bytes(content: bytes) -> pl.DataFrame:
+    """Read a plain (non-geo) parquet response, e.g. a SITS job download."""
+    return pl.read_parquet(io.BytesIO(content))

agrigee_lite_client/_get.py

@@ -0,0 +1,111 @@
+"""Pure request/response helpers shared by the sync and async clients.
+
+Nothing in this module does I/O — it only builds the bytes/dicts to send and
+parses the bytes that come back. The httpx calls and the job poll loop live
+in ``_client.py`` / ``_async_client.py``, since that's the only part that
+actually needs to differ between sync and async (see SPECS.md §4, §8).
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import zipfile
+from typing import Any
+
+import polars as pl
+from shapely.geometry import mapping
+from shapely.geometry.base import BaseGeometry
+
+from agrigee_lite_client import _geoparquet
+
+# ---------------------------------------------------------------------------
+# sits / multiple_sits
+# ---------------------------------------------------------------------------
+
+
+def build_single_sits_frame(geometry: BaseGeometry, start_date: str, end_date: str) -> pl.DataFrame:
+    """1-row frame used by ``get.sits()`` — see SPECS.md §6 ("naive puro")."""
+    wkb = _geoparquet.encode_geometries([geometry])
+    return pl.DataFrame({"start_date": [start_date], "end_date": [end_date], "geometry": wkb})
+
+
+def build_multiple_sits_upload(
+    frame,
+    *,
+    satellite: str,
+    satellite_params: dict[str, Any] | None,
+    reducers: list[str] | None,
+    start_date_column: str,
+    end_date_column: str,
+    original_index_column: str,
+    subsampling_max_pixels: float,
+    chunksize: int,
+    max_parallel_downloads: int,
+    max_retries_per_chunk: int,
+    force_redownload: bool,
+) -> tuple[bytes, dict[str, str]]:
+    """Build the multipart body for ``POST /sits/multiple/file``.
+
+    Returns ``(parquet_bytes, form_fields)``; ``form_fields`` excludes the
+    file itself, which the caller attaches separately as multipart ``file``.
+    CRS is always ``EPSG:4326`` — this client never reprojects (SPECS.md §1).
+    """
+    parquet_bytes = _geoparquet.build_geoparquet_bytes(frame)
+    form: dict[str, str] = {
+        "satellite": json.dumps({"name": satellite, "params": satellite_params or {}}),
+        "start_date_column": start_date_column,
+        "end_date_column": end_date_column,
+        "original_index_column": original_index_column,
+        "subsampling_max_pixels": str(subsampling_max_pixels),
+        "chunksize": str(chunksize),
+        "max_parallel_downloads": str(max_parallel_downloads),
+        "max_retries_per_chunk": str(max_retries_per_chunk),
+        "force_redownload": str(force_redownload).lower(),
+        "crs": "EPSG:4326",
+    }
+    if reducers is not None:
+        form["reducers"] = json.dumps(reducers)
+    return parquet_bytes, form
+
+
+def parse_sits_download(content: bytes) -> pl.DataFrame:
+    return _geoparquet.read_plain_parquet_bytes(content)
+
+
+# ---------------------------------------------------------------------------
+# image
+# ---------------------------------------------------------------------------
+
+
+def build_images_request(
+    geometry: BaseGeometry,
+    *,
+    start_date: str,
+    end_date: str,
+    satellite: str,
+    satellite_params: dict[str, Any] | None,
+    invalid_images_threshold: float,
+    max_parallel_downloads: int,
+    force_redownload: bool,
+    image_indices: list[int] | None,
+    scale: float | None,
+    dimensions: int | str | None,
+) -> dict[str, Any]:
+    """JSON body for ``POST /images`` — a single geometry, no parquet needed."""
+    return {
+        "geometry": mapping(geometry),
+        "start_date": start_date,
+        "end_date": end_date,
+        "satellite": {"name": satellite, "params": satellite_params or {}},
+        "invalid_images_threshold": invalid_images_threshold,
+        "max_parallel_downloads": max_parallel_downloads,
+        "force_redownload": force_redownload,
+        "image_indices": image_indices,
+        "scale": scale,
+        "dimensions": dimensions,
+    }
+
+
+def parse_image_download(content: bytes) -> zipfile.ZipFile:
+    return zipfile.ZipFile(io.BytesIO(content))

agrigee_lite_client/_satellite_dates.py

@@ -0,0 +1,95 @@
+"""Static table of every satellite's temporal range (startDate/endDate).
+
+Generated by scripts/generate_satellite_dates.py from the server's own
+agrigee_lite.api._satellites.REGISTRY — do not hand-edit. Regenerate whenever
+a satellite's date range changes or one is added/removed, then bump both
+packages' version together (SPECS.md §2.1); test_satellite_dates_match_server
+catches drift whenever agrigee_lite happens to be importable alongside this
+package (i.e. in this monorepo's dev environment).
+
+`TwoSatelliteFusion` is intentionally absent: its constructor takes two
+satellite *objects*, not JSON-serializable params, so it was never reachable
+through the `{name, params}` contract this table (and the REST API's
+SatelliteSpec) is built around.
+
+Sentinel2 is the only satellite whose range depends on a constructor param
+(`use_sr`) rather than being fixed per class — handled explicitly in
+get_satellite_date_range() below rather than complicating this table's shape
+for one exception.
+"""
+
+from __future__ import annotations
+
+from agrigee_lite_client._exceptions import AgriGEEUnknownSatelliteError
+
+SATELLITE_DATE_RANGES: dict[str, tuple[str, str]] = {
+    'AHN2Interpolated': ('1900-01-01', '2050-01-01'),
+    'AHN2NonInterpolated': ('1900-01-01', '2050-01-01'),
+    'AHN2Raw': ('1900-01-01', '2050-01-01'),
+    'AHN3': ('1900-01-01', '2050-01-01'),
+    'AHN4': ('1900-01-01', '2050-01-01'),
+    'ALOSWorld3D': ('1900-01-01', '2050-01-01'),
+    'ANADEM': ('1900-01-01', '2050-01-01'),
+    'ASTERDEM': ('1900-01-01', '2050-01-01'),
+    'ArcticDEMMosaic': ('1900-01-01', '2050-01-01'),
+    'ArcticDEMStrips': ('1900-01-01', '2050-01-01'),
+    'Australia5mDEM': ('1900-01-01', '2050-01-01'),
+    'AustraliaDEMH': ('1900-01-01', '2050-01-01'),
+    'AustraliaDEMS': ('1900-01-01', '2050-01-01'),
+    'CGIARSRTM': ('1900-01-01', '2050-01-01'),
+    'CanadaCDEM': ('1900-01-01', '2050-01-01'),
+    'CopernicusDEM': ('1900-01-01', '2050-01-01'),
+    'CryoSat2Antarctica': ('1900-01-01', '2050-01-01'),
+    'ETOPO1': ('1900-01-01', '2050-01-01'),
+    'England1mTerrain': ('1900-01-01', '2050-01-01'),
+    'FranceRGEAlti': ('1900-01-01', '2050-01-01'),
+    'GLOBathy': ('1900-01-01', '2050-01-01'),
+    'GMTED2010': ('1900-01-01', '2050-01-01'),
+    'GTOPO30': ('1900-01-01', '2050-01-01'),
+    'GreenlandGIMP': ('1900-01-01', '2050-01-01'),
+    'HLSLandsat': ('2013-04-11', '2050-01-01'),
+    'HLSSentinel2': ('2015-11-30', '2050-01-01'),
+    'Landsat5': ('1984-03-01', '2013-05-05'),
+    'Landsat7': ('1999-04-15', '2022-04-06'),
+    'Landsat8': ('2013-04-11', '2050-01-01'),
+    'Landsat9': ('2021-11-01', '2050-01-01'),
+    'MERITDEM': ('1900-01-01', '2050-01-01'),
+    'MapBiomas': ('1985-01-01', '2024-01-01'),
+    'Modis8Days': ('2000-02-18', '2050-01-01'),
+    'ModisDaily': ('2000-02-24', '2050-01-01'),
+    'NAIP': ('2003-01-01', '2050-01-01'),
+    'NASADEM': ('1900-01-01', '2050-01-01'),
+    'NEONDEM': ('1900-01-01', '2050-01-01'),
+    'PALSAR2ScanSAR': ('2014-08-04', '2050-01-01'),
+    'PolarisSoilTexture': ('1900-01-01', '2050-01-01'),
+    'REMAMosaic': ('1900-01-01', '2050-01-01'),
+    'REMAStrips2m': ('1900-01-01', '2050-01-01'),
+    'REMAStrips8m': ('1900-01-01', '2050-01-01'),
+    'SRTM': ('1900-01-01', '2050-01-01'),
+    'SatelliteEmbedding': ('2017-01-01', '2024-01-01'),
+    'Sentinel1GRD': ('2014-10-03', '2050-01-01'),
+    'Sentinel2': ('2019-01-01', '2050-01-01'),
+    'USGS3DEP10m': ('1900-01-01', '2050-01-01'),
+    'USGS3DEP1m': ('1900-01-01', '2050-01-01'),
+    'WRBSoilClasses': ('1900-01-01', '2050-01-01'),
+}
+
+
+_SENTINEL2_USE_SR_FALSE = ("2016-01-01", "2050-01-01")
+
+
+def get_satellite_date_range(name: str, params: dict | None = None) -> tuple[str, str]:
+    """(start_date, end_date) for a satellite + params, mirroring the value
+    the server's own satellite class would report for the same inputs.
+    """
+    if name == "Sentinel2" and params and params.get("use_sr") is False:
+        return _SENTINEL2_USE_SR_FALSE
+
+    date_range = SATELLITE_DATE_RANGES.get(name)
+    if date_range is None:
+        msg = (
+            f"agrigee_lite_client does not know satellite {name!r}. Either it doesn't exist, or this "
+            "client's version has drifted from the server's — see SPECS.md §2.1."
+        )
+        raise AgriGEEUnknownSatelliteError(msg)
+    return date_range

agrigee_lite_client/_validation.py

@@ -0,0 +1,91 @@
+"""Client-side mirror of the server's date/satellite-range validation.
+
+Mirrors agrigee_lite/get/sits.py: sanitize_and_prepare_input_gdf — the masking,
+dropping, and logging around rows whose [start_date, end_date) doesn't
+intersect the satellite's temporal range. Applying this before ever opening a
+connection means an impossible request fails immediately and locally instead
+of round-tripping to the server first (and, for `multiple_sits`, before
+uploading a GeoParquet full of rows the server would just drop anyway).
+
+H3 clustering (also part of the server function) is intentionally not
+mirrored here — it's a chunking/performance detail for the server's own
+download scheduling, not part of request validity.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+
+import polars as pl
+
+logger = logging.getLogger(__name__)
+
+
+def _as_datetime_expr(frame: pl.DataFrame, column: str) -> pl.Expr:
+    """pl.col(column).cast(pl.Datetime) silently turns every value into null
+    for a String column as of polars 1.43 (the cast used to parse; that
+    behavior is deprecated/gone, str.to_datetime() is the replacement) — a
+    trap the server itself never hits because it always converts date
+    columns with pandas.to_datetime() before this kind of check runs, but
+    this client hands raw ISO strings straight from sits()/multiple_sits()
+    callers.
+    """
+    if frame.schema[column] == pl.Utf8:
+        return pl.col(column).str.to_datetime(strict=False)
+    return pl.col(column).cast(pl.Datetime, strict=False)
+
+
+def drop_rows_outside_satellite_range(
+    frame: pl.DataFrame,
+    *,
+    satellite_start: str,
+    satellite_end: str,
+    start_date_column: str,
+    end_date_column: str,
+) -> pl.DataFrame:
+    """Drop rows that don't intersect [satellite_start, satellite_end).
+
+    Raises ValueError if *none* of the rows intersect (mirrors the server's
+    behavior exactly). A row with start_date == end_date is dropped too —
+    Earth Engine's date filter treats the end date as exclusive, so a
+    zero-width window is never valid.
+    """
+    working = frame.with_columns(
+        _as_datetime_expr(frame, start_date_column).alias(start_date_column),
+        _as_datetime_expr(frame, end_date_column).alias(end_date_column),
+    )
+
+    sat_start = datetime.fromisoformat(satellite_start)
+    sat_end = datetime.fromisoformat(satellite_end)
+
+    working = working.with_columns(
+        (
+            (pl.col(end_date_column) < pl.lit(sat_start)) | (pl.col(start_date_column) > pl.lit(sat_end))
+        ).alias("_mask_no_intersection"),
+        (pl.col(start_date_column) == pl.col(end_date_column)).alias("_mask_zero_width"),
+    )
+
+    height = working.height
+    count_none = int(working.get_column("_mask_no_intersection").sum())
+    count_zero_width = int(working.get_column("_mask_zero_width").sum())
+
+    pct_none = 100 * count_none / height
+    if pct_none > 0:
+        logger.warning("%.2f%% of the data do not intersect the satellite period.", pct_none)
+
+    if count_zero_width > 0:
+        pct_zero_width = 100 * count_zero_width / height
+        logger.warning(
+            "%d row(s) (%.2f%%) have start_date == end_date and were dropped: Earth Engine's date "
+            "filter treats the end date as exclusive, so a zero-width range is not supported.",
+            count_zero_width,
+            pct_zero_width,
+        )
+
+    if count_none == height:
+        msg = f"None of the requested periods intersect the satellite's temporal range ({satellite_start} to {satellite_end})."
+        raise ValueError(msg)
+
+    drop_mask = pl.col("_mask_no_intersection") | pl.col("_mask_zero_width")
+    return working.filter(~drop_mask).drop("_mask_no_intersection", "_mask_zero_width")

agrigee_lite_client/_version.py

@@ -0,0 +1,10 @@
+"""Single source of truth for this package's version at import time.
+
+Kept separate from __init__.py so _client.py/_async_client.py can import it
+without a circular import (they're imported BY __init__.py). Must always
+equal pyproject.toml's version (SPECS.md §2.1) and, transitively, the
+server's — see also the embedded satellite date table in _satellite_dates.py,
+which is only valid when client and server versions agree.
+"""
+
+__version__ = "3.4.1"

agrigee_lite_client-3.4.1.dist-info/METADATA

@@ -0,0 +1,144 @@
+Metadata-Version: 2.5
+Name: agrigee_lite_client
+Version: 3.4.1
+Summary: Thin HTTP client for the AgriGEE.lite REST API — no Earth Engine, no GDAL, no DuckDB.
+Project-URL: Homepage, https://mateuspinto.github.io/agrigee_lite/
+Project-URL: Repository, https://github.com/mateuspinto/agrigee_lite
+Project-URL: Documentation, https://mateuspinto.github.io/agrigee_lite/
+Author-email: Mateus Pinto da Silva <mateus.p.silva@ufv.br>
+Keywords: python
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: <4.0,>=3.10
+Requires-Dist: geopolars==0.1.0a4
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: shapely>=2.0.0
+Provides-Extra: dev
+Requires-Dist: geopandas>=1.0.1; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.11.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agrigee_lite_client
+
+Thin HTTP client for the [`agrigee_lite[api]`](../README.md) server. Doesn't
+install Earth Engine, GDAL/PROJ, or DuckDB — it only knows how to build a
+request, upload/download bytes, and talk to `/jobs`. See
+[`SPECS.md`](SPECS.md) for the full design and the reasoning behind it.
+
+## Install
+
+```bash
+pip install agrigee_lite_client
+```
+
+One fixed dependency set, always — `geopolars`, `shapely`, and `httpx`.
+There's no install variation (no `[async]`, `[shapely]`, etc. extras): the
+same install already covers both sync and async use.
+
+## Quickstart — sync
+
+```python
+from agrigee_lite_client import AgriGEEClient
+from shapely.geometry import Polygon
+
+geometry = Polygon([(-56.42, -11.20), (-56.41, -11.20), (-56.41, -11.19)])
+
+with AgriGEEClient("http://192.168.3.204:8100") as client:
+    # a single geometry — naive: internally becomes a 1-row multiple_sits
+    df = client.get.sits(geometry, "2023-01-01", "2023-06-01", satellite="Sentinel2")
+
+    # multiple geometries — uploads a GeoParquet, polls the job, downloads the result parquet
+    import polars as pl
+    from agrigee_lite_client._geoparquet import encode_geometries
+
+    gdf = pl.DataFrame({
+        "start_date": ["2023-01-01", "2023-01-01"],
+        "end_date": ["2023-06-01", "2023-06-01"],
+        "geometry": encode_geometries([geometry, geometry]),
+    })
+    df = client.get.multiple_sits(gdf, satellite="Sentinel2", reducers=["mean", "std"])
+
+    # geopandas.GeoDataFrame also works (geopandas is optional — only
+    # imported if you actually pass one; it's not installed alongside the client)
+    import geopandas as gpd
+
+    gdf_geopandas = gpd.GeoDataFrame(
+        {"start_date": ["2023-01-01"], "end_date": ["2023-06-01"]},
+        geometry=[geometry],
+        crs="EPSG:4326",
+    )
+    df = client.get.multiple_sits(gdf_geopandas, satellite="Sentinel2")
+
+    # image — returns an in-memory zipfile.ZipFile, nothing decoded
+    zf = client.get.image(geometry, "2023-01-01", "2023-06-01", satellite="Sentinel2")
+    zf.extractall("out/")
+```
+
+## Quickstart — async
+
+Same surface, `AsyncAgriGEEClient`:
+
+```python
+import asyncio
+from agrigee_lite_client import AsyncAgriGEEClient
+
+async def main():
+    async with AsyncAgriGEEClient("http://192.168.3.204:8100") as client:
+        df = await client.get.sits(geometry, "2023-01-01", "2023-06-01", satellite="Sentinel2")
+
+asyncio.run(main())
+```
+
+## Validation before anything leaves your machine
+
+`sits()`/`multiple_sits()` check that the requested dates actually intersect
+the satellite's operating period — the same check the server does — and
+drop (with a warning) rows that don't, raising `ValueError` if none are
+left. All of this happens **before** building the GeoParquet or opening a
+connection, using a static table embedded in the client (no network call).
+An unknown satellite name is also caught here (`AgriGEEUnknownSatelliteError`).
+
+Since that table is a copy of what the server knows, the client checks that
+it's running against the same server version (via `GET /version`) before
+trusting it — a mismatch raises `AgriGEEVersionMismatchError` instead of
+validating against possibly stale data.
+
+## What this client does NOT do (on purpose)
+
+- No CRS reprojection — input geometries must be in WGS84 (EPSG:4326 /
+  OGC:CRS84). If you pass a `geopandas.GeoDataFrame` with a different CRS,
+  the client rejects it with a clear error instead of reprojecting.
+- No local caching, no sophisticated retry/backoff — the cache already lives
+  on the server; the only "retry" here is `httpx`'s transport timeout and a
+  simple poll loop against `GET /jobs/{id}`.
+- No image decoding — `get.image(...)` returns a raw `zipfile.ZipFile`, no
+  `numpy`/`tifffile`/`rasterio`.
+- `get.sits(...)` isn't a separate fast path: it's sugar over
+  `get.multiple_sits(...)` with a single row, so it pays the job+poll+
+  download cost even for one geometry. See `SPECS.md §6`.
+
+## Versioning
+
+This package's version always matches `agrigee_lite`'s (the server), same
+commit — they aren't versioned independently. A test
+(`tests/test_version_matches_server.py`) enforces this in CI.
+
+## Development
+
+```bash
+cd agrigee_lite_client
+pip install -e ".[dev]"
+pytest
+ruff check .
+```
+
+`tests/test_client_against_live_api.py` only runs if `AGRIGEE_TEST_API_URL`
+is set — the rest (`test_client_mocked.py`, `test_async_client_mocked.py`)
+use `httpx.MockTransport` and need no network.

agrigee_lite_client-3.4.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+agrigee_lite_client/__init__.py,sha256=oEDUvBg-I73ld7_8u-1WU875GLe5Wyi_qnAYhKcfzpw,706
+agrigee_lite_client/_async_client.py,sha256=igMn_lCOXt5vYi4inqJfs56h_oBy9uNmYcwGVmsNh30,7600
+agrigee_lite_client/_client.py,sha256=1VkH8Xextw5ieGjrbFpPgH_USvh2PZ73MWsPCOLZjSU,7453
+agrigee_lite_client/_exceptions.py,sha256=SQSZfzbFiEJusWCLI0AJG62cwLJkcgGRaG-jQ5eSrjY,2155
+agrigee_lite_client/_geo_compat.py,sha256=xUBD0aiabpc7D0MCy2d61e2gTMvLQgJzOQnnDbANu6M,1803
+agrigee_lite_client/_geoparquet.py,sha256=r86mnSNU2jcT7vjRc3p1M3qYxVIvOedHMlxIW3i-yTE,2601
+agrigee_lite_client/_get.py,sha256=IqC8EdocfKOgXOplx8xBLUTt-w1sL9PIJieSJWuHHQw,3936
+agrigee_lite_client/_satellite_dates.py,sha256=8Q_ptzrXr9fVPBNHdfFnjrGluAgAS0H1No5vgMExAu8,4326
+agrigee_lite_client/_validation.py,sha256=MtkGH7rbCHNyoH0Co9C2sZnDx1i7SY1fJE2hFdSKdfc,3748
+agrigee_lite_client/_version.py,sha256=VYwI6Af7wusgH04MJHQ-bTxKf7PXDZ6frugNVXU5_KA,456
+agrigee_lite_client-3.4.1.dist-info/METADATA,sha256=3QsQE1q7DrfUHKdQOXC3p7y5bCtVVLRWyIkXHbCBB6c,5632
+agrigee_lite_client-3.4.1.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+agrigee_lite_client-3.4.1.dist-info/RECORD,,

agrigee_lite_client-3.4.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any