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.

Small files use a single presigned PUT. Large files (at or above multipart_threshold, 100 MB by default) automatically switch to a resumable S3 multipart upload that streams the file in chunks and retries a failed part instead of discarding the whole transfer.

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
DILNAKA_MULTIPART_THRESHOLD=104857600
DILNAKA_UPLOAD_TIMEOUT=300

The SDK base URL is fixed internally to https://dilnaka.storage.tsnc.tech.

• DILNAKA_TIMEOUT (default 60): timeout in seconds for JSON API calls (presign, complete, list, etc.).
• DILNAKA_MULTIPART_THRESHOLD (default 104857600, i.e. 100 MB): files at or above this size use the multipart flow.
• DILNAKA_UPLOAD_TIMEOUT (default 300): per-request transfer timeout in seconds for the single PUT or each multipart part. This is deliberately larger than DILNAKA_TIMEOUT so large chunks over slow links do not time out.

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)

Large file uploads

upload(...) picks the transfer strategy automatically based on file size, so the call is identical for small and large files:

from dilnaka import Dilnaka

client = Dilnaka()

# Uses multipart automatically when the file is >= the threshold (100 MB default).
uploaded = client.upload("./course-bundle.zip")
print(uploaded.id, uploaded.status)

You can tune the behavior per call or per client:

# Force multipart for anything over 25 MB and give each part 10 minutes.
uploaded = client.upload(
    "./course-bundle.zip",
    multipart_threshold=25 * 1024 * 1024,
    upload_timeout=600,
)

The lower-level multipart methods are also available if you need direct control: create_multipart_upload(...), presign_multipart_parts(...), complete_multipart_upload(...), and abort_multipart_upload(...). A failed multipart transfer is aborted automatically so it does not leave a dangling upload on the bucket.

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
POST /v1/uploads/multipart/create
POST /v1/uploads/multipart/parts
POST /v1/uploads/multipart/complete
POST /v1/uploads/multipart/abort
GET  /v1/files
GET  /v1/files/{file_id}
GET  /v1/files/{file_id}/access-url
DELETE /v1/files/{file_id}

The multipart endpoints require the same scopes as the single-PUT flow: uploads:create for multipart/create and multipart/parts, and uploads:complete for multipart/complete and multipart/abort.

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.