Metadata-Version: 2.4
Name: zicon-cloud
Version: 0.1.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)
```

## 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`) without an `api_key` set on the client raises
`ZiconAuthError` immediately, without making a network request.

## Development

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