dilnaka 0.0.6

Python SDK for Dilnaka file uploads

Dilnaka Python SDK

Python SDK for uploading files through the Dilnaka Upload API.

The SDK reads configuration from explicit arguments first, then environment variables. It requests a presigned S3 upload URL from your Dilnaka backend, uploads the file directly to S3, and calls the completion endpoint.

Install

pip install dilnaka

Configure

You can pass configuration directly to Dilnaka(...), or set environment variables for your application.

Configuration precedence is:

1. Explicit constructor arguments such as Dilnaka(base_url=...)
2. Existing process environment variables such as DILNAKA_BASE_URL
3. Values loaded from .env
4. Built-in defaults

If you use a .env file, create it in your application project:

DILNAKA_API_KEY=dlk_dev_your_api_key_here
DILNAKA_BASE_URL=https://dilnaka.tsnc.tech
DILNAKA_TIMEOUT=60

DILNAKA_BASE_URL defaults to https://dilnaka.tsnc.tech and DILNAKA_TIMEOUT defaults to 60.

Basic upload

from dilnaka import Dilnaka

client = Dilnaka()

uploaded = client.upload("./test-upload.txt")

print(uploaded.id)
print(uploaded.key)
print(uploaded.status)

Explicit configuration

from dilnaka import Dilnaka

client = Dilnaka(
    api_key="dlk_dev_your_api_key_here",
    base_url="https://dilnaka.tsnc.tech",
)

uploaded = client.upload("./avatar.png", folder="avatars")
print(uploaded)

Expected backend endpoints

The SDK expects your Caspian backend to expose:

POST /v1/uploads/presign
POST /v1/uploads/complete
GET  /v1/files
GET  /v1/files/{file_id}
DELETE /v1/files/{file_id}

Presign response shape

{
  "fileId": "clx_file_id",
  "fileKey": "uploads/2026/05/clx_file_id-test.txt",
  "uploadUrl": "https://s3-presigned-url",
  "expiresIn": 300,
  "method": "PUT",
  "headers": {
    "Content-Type": "text/plain"
  }
}

Complete response shape

{
  "fileId": "clx_file_id",
  "status": "uploaded",
  "key": "uploads/2026/05/clx_file_id-test.txt",
  "originalName": "test.txt",
  "contentType": "text/plain",
  "size": 94,
  "publicUrl": null
}

Security model

The SDK never receives AWS credentials. It only receives a temporary presigned upload URL from your Dilnaka backend.

Your backend remains responsible for API key validation, scope checking, file validation, S3 key generation, metadata persistence, and upload completion verification.