forcingkit 0.11.0__tar.gz → 0.12.0__tar.gz

{forcingkit-0.11.0 → forcingkit-0.12.0}/.github/workflows/tests.yml

@@ -33,3 +33,18 @@ jobs:
       # Run them locally or via workflow_dispatch.
       - name: Unit tests
         run: uv run python -m pytest tests/unit -m "not integration" --durations=10
+
+  client:
+    name: Client tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      # Its own environment, so a client import of anything from the service stack fails here.
+      - name: Client tests
+        run: uv run --project client python -m pytest client/tests --durations=10

{forcingkit-0.11.0 → forcingkit-0.12.0}/AGENTS.md

@@ -37,6 +37,12 @@ observations for validation.
   Use `python -m pytest` rather than the bare `pytest` entry point: the latter can
   resolve to a system interpreter outside the venv. `tests/conftest.py` puts
   `src/` and `service/` on `sys.path`, so no `PYTHONPATH` export is needed.
+- **Client**: `client/` is a second distribution, `forcingkit-client` (import
+  `forcingkit_client`), with its own `pyproject.toml` and lock. It talks to the service over
+  HTTP only and must never import `forcingkit` or take on the service's dependencies. Test it
+  with `uv run --project client python -m pytest client/tests`. A change to the job routes
+  (`/api/v1/jobs`), the store routes (`/api/v1/stores`) or the STAC Item shape
+  (`service/forcingkit_serve/stac.py`) needs the client and its tests updated with it.
 - **Commits**: Conventional commits (`feat:`, `fix:`, `docs:`, `chore:`).
   Author and committer are always the human contributor (`dfry-lhzn <dfry@lhzn.io>`,
   from `git config`), so the log shows who was behind each change. No `Co-Authored-By:`

{forcingkit-0.11.0 → forcingkit-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: forcingkit
-Version: 0.11.0
+Version: 0.12.0
 Summary: Spatiotemporal forcing for computational Earth-system models: selects, regrids and serves model-ready time series with provenance.
 Project-URL: Documentation, https://forcingkit.docs.lhzn.io
 Project-URL: Issues, https://github.com/lhzn-io/forcingkit/issues
@@ -220,6 +220,7 @@ Requires-Dist: cfgrib>=0.9.15.1
 Requires-Dist: cftime>=1.6.5
 Requires-Dist: dask[array]>=2026.3.0
 Requires-Dist: eccodes>=2.46.0
+Requires-Dist: eccodeslib>=2.46.0
 Requires-Dist: fastapi>=0.135.1
 Requires-Dist: h5netcdf>=1.8.1
 Requires-Dist: h5py>=3.16.0
@@ -238,6 +239,8 @@ Requires-Dist: utide>=0.3.1
 Requires-Dist: uvicorn>=0.41.0
 Requires-Dist: xarray>=2026.2.0
 Requires-Dist: zarr>=3.1.5
+Provides-Extra: gcs
+Requires-Dist: gcsfs>=2026.2.0; extra == 'gcs'
 Description-Content-Type: text/markdown
 
 # <img src="https://raw.githubusercontent.com/lhzn-io/forcingkit/main/static/logo.svg" height="36" valign="middle" alt="Logo" /> forcingkit
@@ -254,7 +257,7 @@ Description-Content-Type: text/markdown
 
 Spatiotemporal forcing for computational Earth-system models: selects, regrids and serves model-ready time series with provenance.
 
-`forcingkit` sits between operational and archive data providers (NOAA HRRR, NECOFS, NOAA OFS, HYCOM, NDBC, CO-OPS) and model codes such as `Oceananigans.jl`. It delivers a model's parent ocean on true z levels (`/api/v1/obc`) and its HRRR surface atmosphere on a regular grid (`/api/v1/atmosphere`), plus station observations for validation, as schema-versioned Zarr stores that record their sources.
+`forcingkit` sits between operational and archive data providers (NOAA HRRR, NWPS, NECOFS, NOAA OFS, HYCOM, NDBC, CO-OPS) and model codes such as `Oceananigans.jl`. It delivers a model's parent ocean on true z levels (`/api/v1/obc`), its HRRR surface atmosphere on a regular grid (`/api/v1/atmosphere`) and NWPS surface waves on the forecast office's own grid (`/api/v1/waves`), plus station observations for validation, as schema-versioned Zarr stores that record their sources.
 
 Documentation: <https://forcingkit.docs.lhzn.io>.
 
@@ -276,6 +279,7 @@ The primary goal of forcingkit is to provide clean, standardized ocean and atmos
 
 - **Oceanic Forcing**: NYOFS, NECOFS, DBOFS, HYCOM (global, 1994 to present).
 - **Atmospheric Forcing**: HRRR (3 km, hourly, 2014-07-30 to present), regridded to 0.03 degrees.
+- **Surface Waves**: NWPS (one forecast office's grid per request, for example OKX CG1 at about 1.8 km, hourly, not regridded). NOMADS keeps about five days; older windows need an NWPS archive (`FORCINGKIT_NWPS_ARCHIVE`).
 
 ## Roadmap
 

{forcingkit-0.11.0 → forcingkit-0.12.0}/README.md

@@ -12,7 +12,7 @@
 
 Spatiotemporal forcing for computational Earth-system models: selects, regrids and serves model-ready time series with provenance.
 
-`forcingkit` sits between operational and archive data providers (NOAA HRRR, NECOFS, NOAA OFS, HYCOM, NDBC, CO-OPS) and model codes such as `Oceananigans.jl`. It delivers a model's parent ocean on true z levels (`/api/v1/obc`) and its HRRR surface atmosphere on a regular grid (`/api/v1/atmosphere`), plus station observations for validation, as schema-versioned Zarr stores that record their sources.
+`forcingkit` sits between operational and archive data providers (NOAA HRRR, NWPS, NECOFS, NOAA OFS, HYCOM, NDBC, CO-OPS) and model codes such as `Oceananigans.jl`. It delivers a model's parent ocean on true z levels (`/api/v1/obc`), its HRRR surface atmosphere on a regular grid (`/api/v1/atmosphere`) and NWPS surface waves on the forecast office's own grid (`/api/v1/waves`), plus station observations for validation, as schema-versioned Zarr stores that record their sources.
 
 Documentation: <https://forcingkit.docs.lhzn.io>.
 
@@ -34,6 +34,7 @@ The primary goal of forcingkit is to provide clean, standardized ocean and atmos
 
 - **Oceanic Forcing**: NYOFS, NECOFS, DBOFS, HYCOM (global, 1994 to present).
 - **Atmospheric Forcing**: HRRR (3 km, hourly, 2014-07-30 to present), regridded to 0.03 degrees.
+- **Surface Waves**: NWPS (one forecast office's grid per request, for example OKX CG1 at about 1.8 km, hourly, not regridded). NOMADS keeps about five days; older windows need an NWPS archive (`FORCINGKIT_NWPS_ARCHIVE`).
 
 ## Roadmap
 

forcingkit-0.12.0/client/README.md

@@ -0,0 +1,27 @@
+# forcingkit-client
+
+A lightweight Python client for a [forcingkit](https://github.com/lhzn-io/forcingkit) service. It
+returns ocean, atmosphere and station forcing as xarray objects, and interpolates forcing along a
+trajectory (a tagged animal, a vessel, a drifter). It depends on `httpx`, `numpy`, `pandas`,
+`scipy`, `xarray` and `zarr` only, none of the service's data-access stack, so it installs into a
+simulator or an application's embedded Python (3.11 or newer).
+
+```python
+from forcingkit_client import Client
+
+fk = Client("http://localhost:9598")
+box = (-70.9, 41.3, -70.6, 41.6)  # west, south, east, north
+ocean = fk.ocean(box, "2025-07-01", 24)  # u, v, temp, salt, zeta
+air = fk.atmosphere(box, "2025-07-01", 24)  # HRRR u10, v10, t2m, ...
+
+# lon, lat, time, z: one value per point; z in metres, positive up
+track = fk.interpolate_trajectory(
+    lon, lat, time, z, variables=("u", "v"), atmosphere=("u10", "v10")
+)
+```
+
+Store builds run as jobs on the service; the client polls them and opens the finished store over
+HTTP through a local cache (`~/.cache/forcingkit-client`), so only the chunks read are fetched,
+once. `AsyncClient` has the same methods for callers that must not block an event loop.
+
+Units are SI; z is metres, positive up. Documentation: <https://forcingkit.docs.lhzn.io/client.html>.

forcingkit-0.12.0/client/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "forcingkit-client"
+version = "0.1.0"
+description = "Lightweight Python client for a forcingkit service: ocean, atmosphere and station forcing as xarray, and forcing interpolated along a trajectory."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+authors = [
+  { name = "Daniel Fry", email = "dfry@lhzn.io" },
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: Atmospheric Science",
+  "Topic :: Scientific/Engineering :: Hydrology",
+]
+# Deliberately small: nothing from the service's stack (GRIB, OPeNDAP, S3), so the client
+# installs into a simulator or an application's embedded Python.
+dependencies = [
+    "httpx>=0.27",
+    "numpy>=1.26",
+    "pandas>=2.2",
+    "scipy>=1.11",
+    "xarray>=2024.10",
+    "zarr>=3.0.8",
+]
+
+[project.urls]
+Documentation = "https://forcingkit.docs.lhzn.io/client.html"
+Issues = "https://github.com/lhzn-io/forcingkit/issues"
+Source = "https://github.com/lhzn-io/forcingkit"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/forcingkit_client"]
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
+]

forcingkit-0.12.0/client/src/forcingkit_client/__init__.py

@@ -0,0 +1,18 @@
+"""Lightweight client for a forcingkit service."""
+
+from .client import AsyncClient, Client, ForcingkitError
+from .schema import SchemaError, normalise
+from .trajectory import interpolate_points, interpolate_trajectory, trajectory_window
+
+__all__ = [
+    "AsyncClient",
+    "Client",
+    "ForcingkitError",
+    "SchemaError",
+    "interpolate_points",
+    "interpolate_trajectory",
+    "normalise",
+    "trajectory_window",
+]
+
+__version__ = "0.1.0"