subnoto-api-client 2.12.0

Python client for the Subnoto Public API

Subnoto Python SDK

Python client for the Subnoto Public API.

Table of contents

• Installation
• Usage
• Configuration
• Error handling and tunnel retry
• Documentation

Installation

Requirements: Python 3.9+

Install from PyPI:

pip install subnoto-api-client

Usage

The SDK provides both async and sync clients. Use SubnotoClient for async/await code or SubnotoSyncClient for synchronous code. Credentials are required; you can pass them explicitly or set SUBNOTO_ACCESS_KEY and SUBNOTO_SECRET_KEY.

Async Example

import asyncio
from subnoto_api_client import SubnotoClient, SubnotoConfig

async def main():
    async with SubnotoClient(SubnotoConfig()) as client:
        response = await client.post("/public/workspace/list", json={})
        print(f"Workspaces: {response.json()}")

if __name__ == "__main__":
    asyncio.run(main())

Sync Example

from subnoto_api_client import SubnotoSyncClient, SubnotoConfig

with SubnotoSyncClient(SubnotoConfig()) as client:
    response = client.post("/public/workspace/list", json={})
    print(f"Workspaces: {response.json()}")

Configuration

Option	Type	Required	Description
access_key	str	Yes	API access key (or set env var SUBNOTO_ACCESS_KEY)
secret_key	str	Yes	API secret key, hex-encoded (or set env var SUBNOTO_SECRET_KEY)

Error handling and tunnel retry

The SDK follows the Subnoto error reference. On tunnel 401 errors (TUNNEL_SESSION_NOT_FOUND or TUNNEL_ERROR), the client automatically invalidates the tunnel session and retries the request up to 3 times with a new session. You do not need to manage tunnel lifecycle when using SubnotoClient or SubnotoSyncClient.

For custom handling you can use the exported helpers and codes. You can raise SubnotoError(message, response.status_code) with the response body message and status code.

from subnoto_api_client import (
    SubnotoClient,
    SubnotoConfig,
    get_error_code,
    is_tunnel_error,
    SubnotoError,
    TUNNEL_SESSION_NOT_FOUND,
    TUNNEL_ERROR,
)

async def main():
    async with SubnotoClient(SubnotoConfig()) as client:
        response = await client.post("/public/utils/whoami", json={})
        if response.status_code != 200:
            body = response.json()
            code = get_error_code(body)  # works with API shape (error.code) and top-level code
            if is_tunnel_error(body):
                # SDK already retried (up to 3 times); this is the result after retries
                pass
            msg = body.get("error", {}).get("message", str(body)) if isinstance(body, dict) else str(body)
            raise SubnotoError(msg, response.status_code)

See the Subnoto error reference for all error codes.

Documentation

The API documentation is available here.