nadeshiko-sdk 0.2.0

Python SDK for Nadeshiko API

This repository is still in WIP and not ready for production use

Nadeshiko Python SDK

Python SDK for the Nadeshiko API

Quick Start

from nadeshiko import Nadeshiko, Environment
from nadeshiko.api.search import search

# Configure your client
client = Nadeshiko(
    api_key='your-api-key-here',
    base_url=Environment.PRODUCTION,  # or Environment.LOCAL, or custom URL
)

# Use API methods (names match OpenAPI operationIds)
result = search.sync(
    client=client,
    body={
        'query': '彼女',
        'limit': 10,
    },
)

if isinstance(result, Error):
    print(result.code, result.detail)
else:
    print(result.sentences)

API Methods

All methods are organized under nadeshiko.api.{module} and match the OpenAPI operationIds exactly:

You can check the full specification from the OpenAPI spec page.

Error Handling

All methods return a union type: Response | Error | None.

Check for errors:

from nadeshiko import Nadeshiko, Environment
from nadeshiko.api.search import search
from nadeshiko.models import Error

client = Nadeshiko(api_key='your-api-key', base_url=Environment.PRODUCTION)
result = search.sync(client=client, body={'query': '彼女'})

if isinstance(result, Error):
    # Error type is fully generated from OpenAPI spec
    print(result.code)    # e.g., 'RATE_LIMIT_EXCEEDED'
    print(result.title)   # e.g., 'Rate Limit Exceeded'
    print(result.detail)  # Detailed message
    print(result.status)  # HTTP status code
else:
    print(result.sentences)

In general, all SDK methods return typed errors generated from the OpenAPI spec:

class Error:
    code: str                 # e.g., 'RATE_LIMIT_EXCEEDED', 'AUTH_CREDENTIALS_INVALID'
    title: str                # Short summary
    detail: str               # Detailed explanation
    status: int               # HTTP status code
    type_: str | Unset        # URI to error documentation
    instance: str | Unset     # Trace ID
    errors: dict | Unset      # Validation errors

Handle each error independently based on the error code returned by the API.

from nadeshiko import Nadeshiko, Environment
from nadeshiko.api.search import search
from nadeshiko.models import Error

client = Nadeshiko(api_key='your-api-key')
result = search.sync(client=client, body={'query': '彼女'})

if isinstance(result, Error):
    # All error fields are typed
    match result.code:
        case 'RATE_LIMIT_EXCEEDED':
            print('Wait before retrying')
        case 'AUTH_CREDENTIALS_INVALID':
            print('Check your API key')
        case 'VALIDATION_FAILED':
            print('Field errors:', result.errors)
        case _:
            print(result.detail)

You can check the full list of errors codes for each endpoint from the OpenAPI spec page.

Type Support

All types are auto-generated from the OpenAPI spec.

from nadeshiko.models import (
    SearchRequest,
    SearchResponse,
    Sentence,
    MediaInfoData,
)

request: SearchRequest = {
    'query': '彼女',
    'limit': 10,
}

sentence: Sentence = {
    'basic_info': { # ... },
    'segment_info': { # ... },
    'media_info': { # ... },
}

Examples

See examples/usage.py for more usage examples.

References

• Nadeshiko Website
• API Documentation