Metadata-Version: 2.5
Name: terrakio-admin-api
Version: 0.9.0
Summary: Admin version of the terrakio-python-api
Requires-Python: >=3.11
Requires-Dist: terrakio-core==0.9.0
Description-Content-Type: text/markdown

# Terrakio Admin API Client

Administrative API client for Terrakio services. This package extends the regular Terrakio API client with additional administrative capabilities.

## Features

- All features from the regular API client
- User management (create, view, edit, delete users)
- Dataset management (create, edit, update, delete datasets)
- Mass stats functionality (create pyramid)

## Installation

```bash
pip install terrakio-admin-api
```

## Usage Example

```python
from terrakio_admin_api import Client

# Initialize the admin client
admin_client = Client()  # defaults to https://dev-omni.terrak.io (fronts all regions)
# or name an environment: Client(env="prod" | "candidate" | "dev-au" | "local" | …),
# settable for a whole session with TERRAKIO_ENV

# Login to your admin account
admin_client.auth.login(email = "XXX", password = "XXX")
print("✓ Login successful")

# The login account will automatically be used for the requests

# View API key
api_key = admin_client.auth.view_api_key()
print(f"✓ Current API key: {api_key[:10]}...")

# Create an extra API key (the full key is returned only here, so store it now)
new_key = admin_client.keys.create_key(label="my laptop")
print(f"✓ New API key: {new_key['key']}")

# List keys (metadata only) and revoke one; pass uid=... to manage another account
for key in admin_client.keys.list_keys():
    print(key["id"], key["prefix"], key["label"])
admin_client.keys.revoke_key(key_id=new_key["id"])

# To rotate a key: create a new one, switch your code over to it, then revoke the old one.

# List number of datasets
datasets = admin_client.datasets.list_datasets()
print(f"✓ Listed {len(datasets)} datasets")

# List number of users
users = admin_client.users.list_users()
print(f"✓ Listed {len(users)} users")
```

## Writing a dataset

A dataset document states its `kind` — `stored` (data in a store), `computed` (an
input expression bound to a registry function) or `loader` (served by a loader
module). Storage presence says where a stored dataset is available: `bucket` for
the cloud, `mount` for the on-prem cluster, either or both. Pyramid settings go in
`zoom`, serve-time settings in `serving`, and the grid in `grid`.

```python
admin_client.datasets.create_dataset(
    name="Rainfall", kind="stored", products=["total"], dates=["2024-01-01"],
    bucket="terrakio-mass-requests", path="rainfall/%s_%s_%03d_%03d_%02d.snp",
    data_type="float32", no_data=-9999, x_size=400, y_size=400, i_max=10, j_max=10,
    grid={"geotransform": geot, "proj4": proj4}, zoom={"max_zoom": 0},
)

admin_client.datasets.create_dataset(
    name="ForestCNN", kind="computed", products=["prob"], dates=["2024-01-01"],
    input="S2v2.red@(year={year})", function="forest_cnn", padding=16,
)
```

The payload is checked against the schema for its kind before the request, so an
off-schema or misplaced field is named locally. `get_dataset` and `list_datasets`
hand back this same shape whichever shape the service stores; pass `raw=True` for
the stored document verbatim.

For more documentation, see the [main repository](https://github.com/HaizeaAnalytics/terrakio-python-api). 