dilnaka 0.0.8

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 and 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 configure the SDK with your API key and optional timeout.

Configuration precedence is:

1. Explicit constructor arguments such as Dilnaka(api_key=...)
2. Existing process environment variables such as DILNAKA_API_KEY
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_TIMEOUT=60

The SDK base URL is fixed internally to https://dilnaka.storage.tsnc.tech. 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",
)

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

Request a file access URL

Use get_file_access_url(...) when you need a URL for downloading or opening a file.

from dilnaka import Dilnaka

client = Dilnaka()

access = client.get_file_access_url("file_123")

print(access.file_id)
print(access.url)
print(access.expires_in)
print(access.is_temporary)

Pass expires_in to request a temporary URL from the backend:

from dilnaka import Dilnaka

client = Dilnaka()

temporary_access = client.get_file_access_url(
  "file_123",
  expires_in=600,
)

print(temporary_access.url)
print(temporary_access.expires_in)   # 600
print(temporary_access.is_temporary) # True

expires_in must be greater than 0. If you omit it, the SDK requests the default access URL returned by your backend.

The method returns a FileAccessUrl object with:

• file_id: Dilnaka file ID
• url: Access URL returned by the API
• expires_in: Expiration time in seconds when the backend returns a temporary URL
• is_temporary: True when the backend marks the URL as temporary, or when an expiration is present

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}
GET  /v1/files/{file_id}/access-url
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
}

Access URL response shape

{
  "fileId": "clx_file_id",
  "url": "https://signed-download-url",
  "expiresIn": 600,
  "isTemporary": true
}

When a temporary URL is requested, the SDK sends:

GET /v1/files/{file_id}/access-url?expiresIn=600

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.