agrigee-lite-client 3.4.1__tar.gz

agrigee_lite_client-3.4.1/.gitignore

@@ -0,0 +1,164 @@
+docs/source
+
+# From https://raw.githubusercontent.com/github/gitignore/main/Python.gitignore
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# Vscode config files
+.vscode/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+
+
+# Specific OS junk files
+*.DS_Store
+core.*
+*:Zone.Identifier
+
+*.parquet
+*.npz
+*.csv
+
+data/
+!data/sample.parquet
+
+
+*.pdf
+*.html
+*.zip
+*.npg
+aria2.session
+# pixi environments
+.pixi/*
+!.pixi/config.toml

agrigee_lite_client-3.4.1/AGENTS.md

@@ -0,0 +1,105 @@
+## AGENTS (compact LLM-oriented) — agrigee_lite_client
+
+Subproject inside the AgriGEE.lite monorepo. See `../AGENTS.md` for the
+server; this file covers only the HTTP client. Read `SPECS.md` in full
+before touching this code — the design decisions (naive on purpose, no
+install extras, geopandas optional-only) are already made and justified
+there; don't reopen them without a new reason.
+
+Run checks:
+
+```bash
+cd agrigee_lite_client
+pip install -e ".[dev]"
+pytest
+ruff check .
+```
+
+## Key rules (short)
+
+- `geopandas` is never a hard dependency, but `multiple_sits()` accepts it as
+  input via lazy detection (`_geo_compat.py`: `try: import geopandas` inside
+  the function, never at module top-level). A top-level `import geopandas`
+  anywhere in the package is a bug — callers who only use `sits()`/geopolars/
+  polars must never pay that import. `geopandas` as a **test-only**
+  dependency (`test_geoparquet.py`, `test_geo_compat.py`) is fine.
+- Fixed dependencies, no extras: `geopolars`, `shapely`, `httpx`. Do not add
+  `[async]`, `[shapely]`, or any optional install variant — explicit user
+  decision, don't reintroduce.
+- Version always matches the server's (`../pyproject.toml`). Every server
+  version bump gets the same bump here, same commit.
+  `tests/test_version_matches_server.py` breaks CI on drift.
+- Sync and async are deliberately duplicated code (`_client.py` /
+  `_async_client.py`) — do not build a sync/async unification layer (e.g.
+  `unasync`) on top. `_get.py` already holds everything that's genuinely
+  shared (payload building, response parsing); only I/O (`httpx` calls,
+  `sleep`/`asyncio.sleep`) is duplicated.
+- `get.sits()` is sugar over `get.multiple_sits()`, not a separate endpoint —
+  don't give it its own HTTP path without reviewing SPECS.md §6 and §11
+  first (a synchronous `/sits/single/file` server endpoint is explicitly
+  deferred future work, don't implement it preemptively).
+- GeoParquet metadata is hand-built (`_geoparquet.py`) via
+  `pyarrow.Table.replace_schema_metadata`, because `geopolars` 0.1.0-alpha.4
+  doesn't write the `"geo"` key on its own (`GeoDataFrame.write_parquet` is
+  the plain `polars.DataFrame.write_parquet`). Reconfirm that behavior on
+  the installed `geopolars` version before changing this approach — it may
+  have changed.
+- CRS is always `EPSG:4326`/`OGC:CRS84` — the client never reprojects. Don't
+  add `pyproj`/reprojection without discussing first (breaks the minimal-
+  dependency promise). A `geopandas.GeoDataFrame` with a different CRS is
+  rejected with `ValueError`, not reprojected.
+- Don't add configurable retry/backoff, local caching, authentication, a
+  CLI, or image decoding (`numpy`/`tifffile`/`rasterio`) without updating
+  SPECS.md §10 first — explicit non-goals of this v1, not oversights.
+- **No new server endpoint just to support this client.** One was proposed
+  (`POST /satellites/date_range`) and rejected — the user didn't want the
+  server growing surface area purely for the client's benefit. `GET
+  /version` is the one exception, added specifically because `/health`
+  already has consumers and must not change shape. Prefer extending an
+  existing endpoint over adding a new one; if that's not possible, ask
+  before adding one.
+- `_satellite_dates.py` is generated, not hand-edited. Regenerate with:
+
+```bash
+python scripts/generate_satellite_dates.py > agrigee_lite_client/_satellite_dates.py
+```
+
+  (needs `agrigee_lite` importable — use the `all-features` pixi env)
+  whenever a satellite is added/removed or its range changes server-side,
+  and bump both packages' version together (SPECS.md §2.1).
+  `test_satellite_dates_match_server.py` catches drift automatically
+  whenever both packages are installed side by side, but doesn't replace
+  regenerating after a real server-side change.
+- `pl.col(...).cast(pl.Datetime, strict=False)` silently nulls a `Utf8`
+  column instead of parsing it, as of polars 1.43 — it used to parse; that
+  behavior is deprecated/gone, `str.to_datetime(strict=False)` is the
+  replacement. Bit this code once (every row got silently dropped).
+  `_validation.py::_as_datetime_expr` checks dtype and picks the right one —
+  don't copy the server's `sanitize_and_prepare_input_gdf` pattern
+  (`agrigee_lite/get/sits.py`) verbatim; it only works there because the
+  column already arrives converted via `pandas.to_datetime`.
+
+## Tests
+
+- `test_geoparquet.py` — no network, validates bytes against
+  `geopandas.read_parquet`.
+- `test_validation.py`, `test_geo_compat.py`, `test_satellite_dates.py` — no
+  network, test `_validation.py`/`_geo_compat.py`/`_satellite_dates.py` in
+  isolation.
+- `test_satellite_dates_match_server.py` — only runs when `agrigee_lite` is
+  importable (`pytest.importorskip`); this is what actually catches drift
+  between the static table and the server's `REGISTRY`.
+- `test_client_mocked.py` / `test_async_client_mocked.py` — no network, use
+  `httpx.MockTransport` + `tests/_fake_server.py` (a stateful fake of the
+  real API: health, version, satellites, job lifecycle). Add new scenarios
+  here, not against a real server.
+- `test_client_against_live_api.py` — only runs with `AGRIGEE_TEST_API_URL`
+  set; not part of the default test run (depends on network + the server's
+  Earth Engine credentials).
+- `test_version_matches_server.py` — always runs, the version lock.
+
+## Docker Hub
+
+This subproject has no image of its own — it's consumed by whoever runs
+`pip install agrigee_lite_client`. The relevant Docker image is the
+server's (`mateuspinto/agrigee-lite`, see `../AGENTS.md`).

agrigee_lite_client-3.4.1/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,117 @@
+# 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/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__",
+]