Metadata-Version: 2.4
Name: currentlab
Version: 0.1.0
Summary: Python library for the Current Lab API
Project-URL: Homepage, https://current-lab.com
Project-URL: Documentation, https://github.com/current-lab/currentlab-python#readme
Project-URL: Repository, https://github.com/current-lab/currentlab-python
Project-URL: Bug Tracker, https://github.com/current-lab/currentlab-python/issues
Author-email: Current Lab <info@current-lab.com>
License: LICENSE
License-File: LICENSE
Keywords: currents,forecast,netcdf,ocean,waves,wind,xarray
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Topic :: Scientific/Engineering :: Oceanography
Requires-Python: >=3.9
Requires-Dist: netcdf4>=1.6
Requires-Dist: requests>=2.28
Requires-Dist: xarray>=2023.1
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: python-dotenv>=1.0; extra == 'dev'
Description-Content-Type: text/markdown

# currentlab-python

The Current Lab Python library provides convenient access to the [Current Lab](https://current-lab.com) API from Python applications. Load gridded forecast files as [xarray](https://docs.xarray.dev) datasets with a single function call.

## Installation

```bash
pip install currentlab
```

## Authentication

Set your API key as an environment variable:

```bash
export CURRENT_LAB_API_KEY="your-api-key"
```

Or use a `.env` file (see `.env.example`) and load it with [python-dotenv](https://pypi.org/project/python-dotenv/).

You can also pass the key directly to any function call via the `api_key=` argument.

## Quick start

```python
import currentlab

ds = currentlab.load_dataset(
    region="oahu",
    dataset_type="currents_surface",
)
print(ds)
```

## API Reference

### `load_dataset(...)`

```python
currentlab.load_dataset(
    region,
    dataset_type,
    dataset_source="auto",
    file_format="netcdf",
    run_date="latest",
    *,
    save_dir=None,
    save_path=None,
    api_key=None,
    base_url="https://api.current-lab.com",
)
```

| Parameter | Type | Description |
|---|---|---|
| `region` | `str` | Region identifier, e.g. `"oahu"` |
| `dataset_type` | `str` | Dataset type, e.g. `"currents_surface"`, `"wave"`, `"wind_10m"`, `"ocean_3d"` |
| `dataset_source` | `str` | Model/source selection. Default `"auto"` lets the server pick the best available source |
| `file_format` | `str` | File format to request. Default `"netcdf"` |
| `run_date` | `str` | Forecast run date as `"YYYY-MM-DD"`, or `"latest"`. Default `"latest"` |
| `save_dir` | `str \| Path` | Directory to save the downloaded file. Filename is derived from the API response. File is reused on subsequent calls if it already exists |
| `save_path` | `str \| Path` | Exact path to save the file to. Reused on subsequent calls if it already exists. Mutually exclusive with `save_dir` |
| `api_key` | `str` | API key override. Falls back to `CURRENT_LAB_API_KEY` env var |
| `base_url` | `str` | API base URL override (useful for testing) |

Returns an `xr.Dataset`.

## Usage patterns

### Stream into memory (no file saved)

A temporary file is created and streamed into memory. The file is deleted after the dataset is closed.

```python
ds = currentlab.load_dataset(region="oahu", dataset_type="wave")
```

### Save to a directory (cached)

File name is derived from the API response.

```python
ds = currentlab.load_dataset(
    region="oahu",
    dataset_type="wave",
    run_date="2025-03-01",
    save_dir="./data",
)
```

### Save to a specific file path (cached)

```python
ds = currentlab.load_dataset(
    region="oahu",
    dataset_type="currents_surface",
    save_path="./data/oahu_currents_latest.nc",
)
```

### Request a specific run date

```python
ds = currentlab.load_dataset(
    region="oahu",
    dataset_type="wind_10m",
    run_date="2026-03-09",
)
```

### Working with the dataset

The returned object is a standard xarray Dataset, so the full xarray API is available:

```python
import numpy as np
import currentlab

ds = currentlab.load_dataset(region="oahu", dataset_type="currents_surface")

# Compute current speed from u/v components
ds["speed"] = np.hypot(ds["u"], ds["v"])
ds["speed"].attrs["long_name"] = "Current Speed"
ds["speed"].attrs["units"] = "m/s"

print(ds["speed"].max().item())
```

## Error handling

```python
from currentlab import CurrentLabAuthError, CurrentLabAPIError, CurrentLabDownloadError

try:
    ds = currentlab.load_dataset(region="oahu", dataset_type="currents_surface")
except CurrentLabAuthError:
    print("Check your CURRENT_LAB_API_KEY.")
except CurrentLabAPIError as e:
    print(f"API error: {e}")
except CurrentLabDownloadError as e:
    print(f"Download failed: {e}")
```

All exceptions inherit from `currentlab.CurrentLabError`.


## Development

```bash
git clone https://github.com/current-lab/currentlab-python
cd currentlab-python
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest
```
