Metadata-Version: 2.1
Name: sustax-client
Version: 0.2.0
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 .`
- published to the GitLab PyPI registry
- later published to PyPI after a final package-name check

## 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
- tests for the parser and client input validation
- Python and R examples
- GitLab CI config for build and package publishing

## Repository layout

```text
sustax-client/
├── .gitignore
├── .gitlab-ci.yml
├── LICENSE
├── README.md
├── pyproject.toml
├── src/
│   └── sustax_client/
│       ├── __init__.py
│       ├── client.py
│       └── parser.py
├── tests/
│   ├── test_client.py
│   └── test_parser.py
└── examples/
    ├── python/
    │   └── quickstart.py
    └── r/
        └── quickstart.R
```

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

If you publish first to the GitLab package registry, use that registry URL in `pip` or `.pypirc`.

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

```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:

```bash
python -m build
```

## Publish to GitLab package registry

The included `.gitlab-ci.yml` publishes a package with `build` and `twine` when a tag is pushed.

Required CI variables:

- `TWINE_USERNAME`
- `TWINE_PASSWORD`

## Before publishing to PyPI

Do these checks first:

1. Confirm the final package name is available on PyPI.
2. Confirm the project license you want to use.
3. Replace the placeholder contact metadata in `pyproject.toml` if needed.
4. Decide whether examples should stay in the main repo or move to docs.

## License

MIT
