sustax-client 0.3.0

Python client and CSV parser for the Sustax User API (SUA)

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

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

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:

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

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

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

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

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:

pytest

Build distributions:

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