Metadata-Version: 2.5
Name: forcingkit-client
Version: 0.1.0
Summary: Lightweight Python client for a forcingkit service: ocean, atmosphere and station forcing as xarray, and forcing interpolated along a trajectory.
Project-URL: Documentation, https://forcingkit.docs.lhzn.io/client.html
Project-URL: Issues, https://github.com/lhzn-io/forcingkit/issues
Project-URL: Source, https://github.com/lhzn-io/forcingkit
Author-email: Long Horizon Observatory <dfry@lhzn.io>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Topic :: Scientific/Engineering :: Hydrology
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.2
Requires-Dist: scipy>=1.11
Requires-Dist: xarray>=2024.10
Requires-Dist: zarr>=3.0.8
Description-Content-Type: text/markdown

# 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>.
