Subnoto Python SDK
Python client for the Subnoto Public API.
Table of contents
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.
2 maintainers
Metadata
2 maintainers
Release files for subnoto-api-client 2.16.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| subnoto_api_client-2.16.1-cp311-abi3-win_amd64.whl | CPython 3.11 | abi3 | Windows x86-64 | Details |
| subnoto_api_client-2.16.1-cp311-abi3-manylinux2014_x86_64.whl | CPython 3.11 | abi3 | Linux glibc 2.17+ x86-64 | Details |
| subnoto_api_client-2.16.1-cp311-abi3-manylinux2014_aarch64.whl | CPython 3.11 | abi3 | Linux glibc 2.17+ ARM64 | Details |
| subnoto_api_client-2.16.1-cp311-abi3-macosx_11_0_arm64.whl | CPython 3.11 | abi3 | macOS 11.0+ ARM64 | Details |
Total release size: 8.1 MB
Release files / subnoto_api_client-2.16.1-cp311-abi3-win_amd64.whl
| Download URL | subnoto_api_client-2.16.1-cp311-abi3-win_amd64.whl |
|---|---|
| Size | 2.0 MB |
| Tags | CPython 3.11 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
3b62f4d8a07e642f39233674e2adc8f44e3fc17f8687a20079d9497b6a47d5d1
|
|
BLAKE2b-256 checksum How to use checksums |
d6f4ebceff80e241382cb40971afb88f1a5769ae37d438e31413ad253758016a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.2.0 CPython/3.12.11
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitLab CI/CD, verified by PyPI on Jun 29, 2026.
Transparency logRelease files / subnoto_api_client-2.16.1-cp311-abi3-manylinux2014_x86_64.whl
| Download URL | subnoto_api_client-2.16.1-cp311-abi3-manylinux2014_x86_64.whl |
|---|---|
| Size | 2.1 MB |
| Tags | CPython 3.11 Linux glibc 2.17+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
4f51559e3b338e4b3e49f40642e48ab5d041c31587fb7e9ed12e815ccc6dd630
|
|
BLAKE2b-256 checksum How to use checksums |
71ade888a9e8fe332836261a3f803edee2537579bca40ffcf330f77729df8217
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.2.0 CPython/3.12.11
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitLab CI/CD, verified by PyPI on Jun 29, 2026.
Transparency logRelease files / subnoto_api_client-2.16.1-cp311-abi3-manylinux2014_aarch64.whl
| Download URL | subnoto_api_client-2.16.1-cp311-abi3-manylinux2014_aarch64.whl |
|---|---|
| Size | 2.0 MB |
| Tags | CPython 3.11 Linux glibc 2.17+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
21ab7010fcb64ed9d0c8d32a57396064bf17055cd7ad3223145e15dca3a1405c
|
|
BLAKE2b-256 checksum How to use checksums |
b6397ff61181f06df1cb38fe13f9de183d97a6da8487920c3a52ded28eabdc36
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.2.0 CPython/3.12.11
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitLab CI/CD, verified by PyPI on Jun 29, 2026.
Transparency logRelease files / subnoto_api_client-2.16.1-cp311-abi3-macosx_11_0_arm64.whl
| Download URL | subnoto_api_client-2.16.1-cp311-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 2.1 MB |
| Tags | CPython 3.11 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
c4ad336982574cf2ff201cba1f7e422ccb189990785504d0d444e7396db99552
|
|
BLAKE2b-256 checksum How to use checksums |
a682eb0752e6a650c6b42a9a6f45886204c38289664d639998500cda1cd4cd43
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.2.0 CPython/3.12.11
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitLab CI/CD, verified by PyPI on Jun 29, 2026.
Transparency log
