Metadata-Version: 2.4
Name: zicon-cloud
Version: 0.2.0
Summary: Python SDK for the ZiCON Cloud API
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.20
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"

# zicon-cloud

Python SDK for the [ZiCON Cloud](https://bwwzefaddmyueynayize.supabase.co) API.

## Installation

```bash
pip install zicon-cloud
```

## Quickstart

```python
from zicon_cloud import ZiconClient

# Public endpoints work without an API key
client = ZiconClient()

# Authenticated endpoints require an api_key
client = ZiconClient(api_key="YOUR_ZICON_API_KEY")
```

## Usage

### List datasets (no auth required)

```python
from zicon_cloud import ZiconClient

client = ZiconClient()
datasets = client.list_datasets()
print(datasets)
```

### Get a single dataset (no auth required)

```python
dataset = client.get_dataset("dataset-id")
print(dataset)
```

### List projects (requires API key)

```python
from zicon_cloud import ZiconClient

client = ZiconClient(api_key="YOUR_ZICON_API_KEY")
projects = client.list_projects()
print(projects)
```

### Get files for a project (requires API key)

```python
files = client.get_project_files("project-id")
print(files)
```

### Get a file download URL (requires API key)

```python
download_url = client.get_download_url("file-id")
print(download_url)
```

### List endpoints (no auth required)

```python
endpoints = client.list_endpoints()
print(endpoints)
```

### List tools (no auth required)

```python
tools = client.list_tools()
print(tools)
```

### Download a dataset (no auth required)

```python
download = client.download_dataset("dataset-id")
print(download)
```

### Delete a project (requires API key)

```python
client = ZiconClient(api_key="YOUR_ZICON_API_KEY")
client.delete_project("project-id")
```

### Create a project (requires an access token)

`create_project` authenticates differently from the other methods above: it
takes an `access_token` argument and sends it as an `Authorization: Bearer`
header, instead of using the client's `api_key`.

```python
from zicon_cloud import ZiconClient

client = ZiconClient()
project = client.create_project(
    name="My Project",
    category="research",
    description="A project created via the SDK",
    access_token="YOUR_ACCESS_TOKEN",
)
print(project)
```

## Error handling

The SDK raises typed exceptions based on the API response:

```python
from zicon_cloud import (
    ZiconClient,
    ZiconAuthError,
    ZiconPermissionError,
    ZiconNotFoundError,
    ZiconServerError,
)

client = ZiconClient(api_key="YOUR_ZICON_API_KEY")

try:
    projects = client.list_projects()
except ZiconAuthError:
    print("Invalid or missing API key")
except ZiconPermissionError:
    print("Your API key doesn't have permission for this")
except ZiconNotFoundError:
    print("Resource not found")
except ZiconServerError:
    print("ZiCON Cloud is having server issues, try again later")
```

Calling an authenticated method (`list_projects`, `get_project_files`,
`get_download_url`, `delete_project`) without an `api_key` set on the client
raises `ZiconAuthError` immediately, without making a network request.
Likewise, calling `create_project` without an `access_token` raises
`ZiconAuthError` immediately.

## Development

```bash
pip install -e ".[test]"
pytest
```
