Python SDK

The TaruviBase Python SDK provides native synchronous and asynchronous clients for backends, jobs, scripts, notebooks, and automation. Both modes expose the same product module families.

This guide covers the taruvi Python package. The package requires Python 3.10 or newer and explicitly declares Python 3.10–3.13.

Install the SDK

python -m pip install taruvi

Create a synchronous client

Select sync mode explicitly and use the client as a context manager so the HTTP connection is closed when the operation finishes:

import os

from taruvi import Client

with Client(
    api_url=os.environ["TARUVI_SITE_URL"],
    app_slug=os.environ["TARUVI_APP_SLUG"],
    api_key=os.environ["TARUVI_API_KEY"],
    mode="sync",
) as client:
    client.database.from_("tasks").page_size(20).execute()

Create an asynchronous client

Select async mode inside an event loop and await both product calls and client cleanup:

import asyncio
import os

from taruvi import Client

async def main():
    async with Client(
        api_url=os.environ["TARUVI_SITE_URL"],
        app_slug=os.environ["TARUVI_APP_SLUG"],
        session_token=os.environ["TARUVI_SESSION_TOKEN"],
        mode="async",
    ) as client:
        await client.database.from_("tasks").page_size(20).execute()


asyncio.run(main())

Keeping mode explicit makes the execution model clear. When it is omitted, the factory chooses async mode inside a running event loop and sync mode otherwise.

Client requires api_url and app_slug; timeout defaults to 120 seconds and max_retries defaults to 3. Select mode explicitly in reusable code.

Choose an authentication method

The client accepts one of three request credentials:

Client option	Request header
api_key	Authorization: Api-Key <value>
jwt	Authorization: Bearer <value>
session_token	X-Session-Token: <value>

Use api_key for services, jobs, and scripts; generate the key on your app's Settings → Connect page. Use session_token when your backend acts for a signed-in user and receives that user's session token from your frontend.

Load credentials from the runtime environment or secret store. Do not commit them to application source.

The auth module can also return a new authenticated client from a token or an email/password flow. When you use that pattern, close both the original and the returned client after use.

Use a product module

Sync and async clients expose:

• auth
• database
• storage
• functions
• secrets
• policy
• app
• settings
• users
• analytics

The product guide determines which operations are available and which permissions they require. Use the Products overview to choose a capability, then keep the client configuration outside the individual operation snippets.

Handle errors

The SDK maps common HTTP failures to typed exceptions. Catch the cases your application can recover from and use TaruviError as the SDK-level fallback:

from taruvi import AuthorizationError, NotFoundError, TaruviError

try:
    client.database.from_("tasks").get("task-id").execute()
except AuthorizationError:
    ...
except NotFoundError:
    ...
except TaruviError as error:
    status_code = error.status_code
    details = error.details

Read the installed distribution version with importlib.metadata.version("taruvi"). Pin it in the application dependency file and test authentication, reads, writes, permission failures, and cleanup before upgrading.

Choose a task from the Products overview for focused SDK methods and examples.

Deploy your app

Once you've built your application with the Python SDK, set up automated deployments to production:

Deploy with GitHub Actions →