dilnaka 0.0.9

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.

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.