Skip to main content

Dateno Python SDK — Usage & Examples

Overview​

This document provides practical examples of using the Dateno Python SDK to interact with the Dateno API.

All SDK responses are returned as Pydantic models.

Creating an SDK Client​

Synchronous client​

from dateno import SDK

with SDK(api_key_query="YOUR_API_KEY") as sdk:
    # use sdk here
    pass

Asynchronous client​

import asyncio
from dateno import SDK

async def main():
    async with SDK(api_key_query="YOUR_API_KEY") as sdk:
        pass

asyncio.run(main())

Basic Flow​

  1. Create the SDK client with your API key
  2. Call an API method
  3. Handle errors (if any)
from dateno import SDK, errors

try:
    with SDK(api_key_query="YOUR_API_KEY") as sdk:
        res = sdk.search_api.search_datasets(q="economy", limit=1)
        print(res.hits.hits[0].id if res.hits.hits else "no hits")
except errors.SDKError as exc:
    print("SDK error:", exc)

Selecting Environment (Prod/Test)​

By default, the SDK targets production. You can point it to test:

from dateno import SDK

sdk = SDK(
    api_key_query="YOUR_API_KEY",
    server_url="https://api.test.dateno.io",
)

Working with Data Catalogs​

Get a catalog by ID​

from dateno import SDK

with SDK(api_key_query="YOUR_API_KEY") as sdk:
    catalog = sdk.data_catalogs_api.get_catalog_by_id(
        catalog_id="cdi00001616"
    )
    print(catalog)

Async version​

catalog = await sdk.data_catalogs_api.get_catalog_by_id_async(
    catalog_id="cdi00001616"
)

Searching Datasets​

from dateno import SDK

with SDK(api_key_query="YOUR_API_KEY") as sdk:
    resp = sdk.search_api.search_datasets(
        q="environment",
        limit=20,
        offset=0,
    )

    for hit in resp.hits.hits:
        print(hit.id, hit.source.dataset.title)

Pagination & Limits​

⚠️ Important

For dataset search endpoints, the API enforces:

  • Maximum limit = 500
  • Values greater than 500 are silently clamped

Correct pagination example​

PAGE_SIZE = 500
offset = 0

with SDK(api_key_query="YOUR_API_KEY") as sdk:
    while True:
        resp = sdk.search_api.search_datasets(
            q="economy",
            limit=PAGE_SIZE,
            offset=offset,
        )

        hits = resp.hits.hits
        if not hits:
            break

        for hit in hits:
            print(hit.id)

        offset += PAGE_SIZE

Working with Service Endpoints​

Health check​

from dateno import SDK

with SDK(api_key_query="YOUR_API_KEY") as sdk:
    health = sdk.service.get_healthz()
    print(health)

Error Handling​

All SDK-level errors inherit from SDKError.

from dateno import SDK, errors

try:
    with SDK(api_key_query="YOUR_API_KEY") as sdk:
        sdk.service.get_healthz()
except errors.SDKError as exc:
    print("SDK error:", exc)

Async vs Sync — When to Use Which​

  • Sync:

    • Scripts
    • CLI tools
    • Simple integrations

  • Async:

    • Web services (FastAPI, aiohttp)
    • High-concurrency workloads
    • Batch processing

Client Identification Header (Dateno-Client)​

The SDK automatically sends Dateno-Client: sdk-python/<version> on each request. You can override it per call using http_headers:

from dateno import SDK

with SDK(api_key_query="YOUR_API_KEY") as sdk:
    resp = sdk.search_api.search_datasets(
        q="environment",
        limit=1,
        http_headers={"Dateno-Client": "myapp/1.2.3"},
    )

Pagination Helpers​

from dateno import SDK

with SDK(api_key_query="YOUR_API_KEY") as sdk:
    for hit in sdk.search_api.paginate_search_datasets(q="environment", limit=500):
        print(hit.id)

Timeouts and Retries​

from dateno import SDK
from dateno.utils import RetryConfig

sdk = SDK(
    api_key_query="YOUR_API_KEY",
    timeout_ms=10_000,
    retry_config=RetryConfig(max_retries=2),
)