Metadata-Version: 2.1
Name: sustax_client
Version: 0.3.2
Summary: Python client and CSV parser for the Sustax User API (SUA)
Author-email: Geoskop Sociedad Limitada <info@geoskop.tech>
Maintainer-email: Matthew Barrett <info@geoskop.tech>
License: MIT
Project-URL: Homepage, https://sustax.earth
Project-URL: Documentation, https://sustax.earth/docs/workflows-and-pipelines-how-to-pass-sustax-data-to-different-interpreters-2/
Project-URL: Source, https://gitlab.com/joan.saladich/sustax-client
Project-URL: Repository, https://gitlab.com/joan.saladich/sustax-client
Project-URL: Issues, https://gitlab.com/joan.saladich/sustax-client/-/issues
Project-URL: Examples, https://gitlab.com/joan.saladich/sustax-client/-/tree/main/examples
Keywords: sustax,climate,api,csv,geoskop,era5,ssp,climate-data
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: requests>=2.31
Requires-Dist: urllib3>=2.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"

# sustax-client

A small Python package for the **Sustax User API** and for parsing the Sustax global climate models by means of CSV files exported by Sustax (see https://sustax.earth). This repository is prepared in a standard `src/` layout so it can be:

- developed locally with `pip install -e .`
- installed from a Python package registry
- built as a source distribution and wheel

## What is included

- `SustaxClient` for authentication, catalog lookup, pricing, purchases, downloads, status polling, coordinates, and balance checks
- `load_sustax_file()` to load Sustax CSV files into pandas DataFrames or nested numpy-friendly dictionaries
- parser, parsing, and reranking helpers for Sustax CSV outputs
- Python examples for catalog inspection, coordinate downloads, and postal-code downloads
- unit tests plus marked live API and purchase workflow tests

## Repository layout

```text
sustax-client/
├── .gitignore
├── CONTRIBUTING.md
├── LICENSE
├── MANIFEST.in
├── README.md
├── pytest.ini
├── pyproject.toml
├── src/
│   └── sustax_client/
│       ├── __init__.py
│       ├── client.py
│       ├── parser.R
│       ├── parser.py
│       ├── parsing.py
│       └── reranking.py
├── tests/
│   ├── test_reranking.py
│   ├── test_sustax_downloaded_csv_values.py
│   └── test_sustax_workflow.py
└── examples/
    ├── _helpers.py
    ├── download_coords.py
    ├── download_zip_code.py
    └── inspect_catalog.py
```

## Installation

### Local development

```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .[dev]
```

### From a package registry

Once published:

```bash
pip install sustax-client
```

## Quick start

### 1. Authenticate and inspect the catalog

```python
from sustax_client import SustaxClient

with SustaxClient() as client:
    client.authenticate("your_username", "your_password")
    catalog = client.get_variables_id()
    print(catalog)
```

### 2. Preview pricing for a point request

```python
from sustax_client import SustaxClient

with SustaxClient() as client:
    client.authenticate("your_username", "your_password")
    quote = client.view_price_request(
        lat=41.3874,
        lon=2.1686,
        year_from=2020,
        year_to=2030,
        sustax_code_ids=[12345],
    )
    print(quote)
```

### 3. Buy, download, and unzip a request

This example purchases data and may spend Sustax coins.

```python
from sustax_client import SustaxClient

with SustaxClient() as client:
    client.authenticate("your_username", "your_password")
    request_info = client.buy_data(
        lat=41.3874,
        lon=2.1686,
        year_from=2020,
        year_to=2030,
        sustax_code_ids=[12345],
        acceptance_sustax_disclaimer=True,
    )
    zip_path = client.download_file(request_info["url"], dest_dir="downloads")
    extracted = client.unzip_download(dest_dir="downloads/unzipped")
    print(zip_path)
    print(extracted)
```

### 4. Load a Sustax CSV with pandas

```python
from sustax_client import load_sustax_file

climate_df, metrics_df, metadata = load_sustax_file(
    "downloads/unzipped/example.csv",
    return_pandas_df=True,
    return_metadata=True,
)

print(climate_df.head())
print(metrics_df.head())
print(metadata)
```

## Supported request modes

The packaged client supports the three location modes described in the Sustax documentation:

- point coordinates: `lat`, `lon`
- ROI / bounding box: `lat=[north, south]`, `lon=[west, east]`
- postal code lookup: `postal_code`, `country`

## CSV parser behavior

`load_sustax_file()` assumes the exported file is a Sustax CSV with three main blocks:

- metadata
- accuracy metrics
- climate payload time series

By default it returns two pandas DataFrames:

- climate payload indexed by time
- metrics indexed by scenario

Set `return_pandas_df=False` if you prefer nested dictionaries and a numpy datetime array.

## Development

Run tests:

```bash
pytest
```

Build distributions locally:

```bash
python -m build
```

## License

MIT
