zicon-cloud

Python SDK for the ZiCON Cloud API.

Installation

pip install zicon-cloud

Quickstart

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)

from zicon_cloud import ZiconClient

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

Get a single dataset (no auth required)

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

Get dataset contents (no auth required)

contents = client.get_dataset_contents("dataset-id")
print(contents)

List projects (requires API key)

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)

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

Get a file download URL (requires API key)

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

List endpoints (no auth required)

endpoints = client.list_endpoints()
print(endpoints)

List tools (no auth required)

tools = client.list_tools()
print(tools)

Download a dataset (no auth required)

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

Delete a project (requires API key)

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.

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:

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

pip install -e ".[test]"
pytest