nerdstack-ark 1.0.0__py3-none-any.whl

ark_py/models.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Literal
+
+
+@dataclass(frozen=True, slots=True)
+class ArkFile:
+    id: str
+    name: str
+    original_name: str
+    size: int
+    mime_type: str
+    folder_id: str | None
+    status: str
+    checksum: str | None
+    url: str
+    created_at: str | None
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> ArkFile:
+        return cls(
+            id=str(value["id"]),
+            name=str(value["name"]),
+            original_name=str(value.get("originalName", value["name"])),
+            size=int(value["size"]),
+            mime_type=str(value.get("mimeType") or "application/octet-stream"),
+            folder_id=_optional_string(value.get("folderId")),
+            status=str(value.get("status") or "available"),
+            checksum=_optional_string(value.get("checksum")),
+            url=str(value.get("url") or ""),
+            created_at=_optional_string(value.get("createdAt")),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class ArkFolder:
+    id: str
+    name: str
+    parent_id: str | None
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> ArkFolder:
+        return cls(
+            id=str(value["id"]),
+            name=str(value["name"]),
+            parent_id=_optional_string(value.get("parentId")),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class StorageUsage:
+    used_bytes: int
+    pending_bytes: int
+    limit_bytes: int
+    available_bytes: int
+
+
+@dataclass(frozen=True, slots=True)
+class ArkUsage:
+    storage: StorageUsage
+    tier: Literal["free", "paid"] | str
+    status: str
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> ArkUsage:
+        storage = value.get("storage")
+        if not isinstance(storage, Mapping):
+            storage = {}
+        return cls(
+            storage=StorageUsage(
+                used_bytes=int(storage.get("usedBytes", 0)),
+                pending_bytes=int(storage.get("pendingBytes", 0)),
+                limit_bytes=int(storage.get("limitBytes", 0)),
+                available_bytes=int(storage.get("availableBytes", 0)),
+            ),
+            tier=str(value.get("tier") or "free"),
+            status=str(value.get("status") or "active"),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class FilePage:
+    data: tuple[ArkFile, ...]
+    next_cursor: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class ClientSession:
+    token: str
+    expires_at: str
+    expires_in_seconds: int
+    scopes: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class ImageOptions:
+    width: int | None = None
+    height: int | None = None
+    quality: int | None = None
+    format: Literal["original", "jpeg", "png", "webp", "avif"] = "original"
+    thumbnail: bool = False
+    watermark: bool = False
+
+
+def _optional_string(value: object) -> str | None:
+    return value if isinstance(value, str) else None

ark_py/py.typed

@@ -0,0 +1 @@
+# PEP 561 marker

ark_py/s3.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def create_s3_client(
+    *,
+    access_key_id: str,
+    secret_access_key: str,
+    endpoint_url: str = "https://ark.nerdstackgrp.com/s3",
+    region_name: str = "auto",
+    **kwargs: Any,
+) -> Any:
+    """Create a path-style boto3 S3 client configured for Ark.
+
+    Install the optional dependency with ``pip install nerdstack-ark[s3]``.
+    Ark credentials authenticate only against Ark and are not provider keys.
+    """
+    try:
+        import boto3  # type: ignore[import-not-found]
+        from botocore.config import Config  # type: ignore[import-not-found]
+    except ImportError as error:
+        raise ImportError(
+            "S3 support requires boto3; install it with 'pip install nerdstack-ark[s3]'"
+        ) from error
+
+    config = kwargs.pop("config", None)
+    if config is None:
+        config = Config(signature_version="s3v4", s3={"addressing_style": "path"})
+    return boto3.client(
+        "s3",
+        endpoint_url=endpoint_url,
+        region_name=region_name,
+        aws_access_key_id=access_key_id,
+        aws_secret_access_key=secret_access_key,
+        config=config,
+        **kwargs,
+    )

ark_py/sync.py

@@ -0,0 +1,381 @@
+from __future__ import annotations
+
+import builtins
+from collections.abc import Mapping
+from concurrent.futures import FIRST_COMPLETED, Future, ThreadPoolExecutor, wait
+from contextlib import suppress
+from pathlib import Path
+from types import TracebackType
+from typing import Any, BinaryIO, TypeVar, cast
+
+import httpx
+
+from ._shared import (
+    DEFAULT_BASE_URL,
+    UploadSource,
+    api_url,
+    ensure_stream_complete,
+    image_url,
+    iter_exact,
+    iter_file_range,
+    parse_client_session,
+    query_string,
+    read_exact,
+    resolve_upload_source,
+    segment,
+    sorted_parts,
+    upload_payload,
+)
+from .errors import ArkError, error_from_response, network_error, upload_error
+from .models import ArkFile, ArkFolder, ArkUsage, ClientSession, FilePage, ImageOptions
+
+T = TypeVar("T")
+
+
+class Ark:
+    """Synchronous Ark client for Django, Flask, Celery, scripts, and workers."""
+
+    def __init__(
+        self,
+        token: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        version: str = "v2",
+        timeout: float | httpx.Timeout = 30.0,
+        client: httpx.Client | None = None,
+    ) -> None:
+        if not token:
+            raise ArkError("UNAUTHORIZED", "An Ark API token is required")
+        self._token = token
+        self._base_url = base_url.rstrip("/")
+        self._version = version
+        self._client = client or httpx.Client(timeout=timeout, follow_redirects=True)
+        self._owns_client = client is None
+        self.files = Files(self)
+        self.folders = Folders(self)
+        self.images = Images(self)
+        self.imports = Imports(self)
+
+    def __enter__(self) -> Ark:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def usage(self) -> ArkUsage:
+        return ArkUsage.from_dict(self._request("GET", "/usage"))
+
+    def create_client_session(
+        self,
+        *,
+        scopes: list[str] | None = None,
+        folder_id: str | None = None,
+        ttl_seconds: int | None = None,
+    ) -> ClientSession:
+        payload: dict[str, Any] = {}
+        if scopes is not None:
+            payload["scopes"] = scopes
+        if folder_id is not None:
+            payload["folderId"] = folder_id
+        if ttl_seconds is not None:
+            payload["ttlSeconds"] = ttl_seconds
+        return parse_client_session(self._request("POST", "/client-sessions", json=payload))
+
+    def _url(self, path: str) -> str:
+        return api_url(self._base_url, self._version, path)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Mapping[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        try:
+            response = self._client.request(
+                method,
+                self._url(path),
+                headers={"authorization": f"Bearer {self._token}"},
+                json=dict(json) if json is not None else None,
+            )
+        except httpx.HTTPError as error:
+            raise network_error(error) from error
+        if response.is_error:
+            raise error_from_response(response)
+        if response.status_code == 204:
+            return {}
+        value = response.json()
+        if not isinstance(value, dict):
+            raise ArkError("INTERNAL_ERROR", "Ark returned an invalid JSON response")
+        return cast(dict[str, Any], value)
+
+
+class Files:
+    def __init__(self, ark: Ark) -> None:
+        self._ark = ark
+
+    def list(
+        self,
+        *,
+        folder_id: str | None = None,
+        limit: int | None = None,
+        cursor: str | None = None,
+    ) -> FilePage:
+        suffix = query_string({"folderId": folder_id, "limit": limit, "cursor": cursor})
+        value = self._ark._request("GET", f"/files{suffix}")
+        raw_data = value.get("data")
+        data = tuple(
+            ArkFile.from_dict(item)
+            for item in (raw_data if isinstance(raw_data, list) else [])
+            if isinstance(item, Mapping)
+        )
+        next_cursor = value.get("nextCursor")
+        return FilePage(data, next_cursor if isinstance(next_cursor, str) else None)
+
+    def get(self, file_id: str) -> ArkFile:
+        return ArkFile.from_dict(self._ark._request("GET", f"/files/{segment(file_id)}"))
+
+    def delete(self, file_id: str) -> bool:
+        value = self._ark._request("DELETE", f"/files/{segment(file_id)}")
+        return bool(value.get("deleted"))
+
+    def move(self, file_id: str, folder_id: str | None) -> ArkFile:
+        value = self._ark._request(
+            "PATCH",
+            f"/files/{segment(file_id)}",
+            json={"folderId": folder_id},
+        )
+        return ArkFile.from_dict(value)
+
+    def get_download_url(self, file_id: str, *, expires_in_seconds: int | None = None) -> str:
+        payload: dict[str, Any] = {"fileId": file_id}
+        if expires_in_seconds is not None:
+            payload["expiresInSeconds"] = expires_in_seconds
+        value = self._ark._request("POST", "/downloads/presign", json=payload)
+        return str(value["url"])
+
+    def upload(
+        self,
+        source: str | Path | BinaryIO,
+        *,
+        size: int | None = None,
+        filename: str | None = None,
+        content_type: str | None = None,
+        folder_id: str | None = None,
+        metadata: Mapping[str, Any] | None = None,
+    ) -> ArkFile:
+        resolved = resolve_upload_source(
+            source,
+            size=size,
+            filename=filename,
+            content_type=content_type,
+        )
+        session = self._ark._request(
+            "POST",
+            "/uploads/presign",
+            json=upload_payload(
+                resolved.filename,
+                resolved.size,
+                resolved.content_type,
+                folder_id,
+                metadata,
+            ),
+        )
+        upload_id = str(session["uploadId"])
+        try:
+            parts = self._upload_transfer(resolved, session)
+            completion: dict[str, Any] = {}
+            if parts is not None:
+                completion["parts"] = parts
+            value = self._ark._request(
+                "POST",
+                f"/uploads/{segment(upload_id)}/complete",
+                json=completion,
+            )
+            return ArkFile.from_dict(value)
+        except BaseException:
+            with suppress(ArkError):
+                self._ark._request("POST", f"/uploads/{segment(upload_id)}/abort", json={})
+            raise
+
+    def _upload_transfer(
+        self,
+        source: UploadSource,
+        session: Mapping[str, Any],
+    ) -> builtins.list[dict[str, object]] | None:
+        if not session.get("multipart"):
+            url = str(session["url"])
+            session_headers = session.get("headers")
+            headers = {
+                "content-type": source.content_type,
+                "content-length": str(source.size),
+                **(
+                    {str(key): str(value) for key, value in session_headers.items()}
+                    if isinstance(session_headers, Mapping)
+                    else {}
+                ),
+            }
+            content = (
+                iter_file_range(source.path, 0, source.size)
+                if source.path is not None
+                else iter_exact(cast(BinaryIO, source.stream), source.size)
+            )
+            self._put(url, content, headers=headers)
+            return None
+        return self._upload_multipart(source, session)
+
+    def _upload_multipart(
+        self,
+        source: UploadSource,
+        session: Mapping[str, Any],
+    ) -> builtins.list[dict[str, object]]:
+        raw_parts = session.get("parts")
+        if not isinstance(raw_parts, list) or not raw_parts:
+            raise ArkError("INTERNAL_ERROR", "Ark returned an invalid multipart session")
+        part_size = int(session["partSize"])
+        concurrency = max(1, min(int(session.get("maxConcurrency") or 4), len(raw_parts)))
+        results: list[dict[str, object]] = []
+        pending: set[Future[dict[str, object]]] = set()
+
+        def collect(done: set[Future[dict[str, object]]]) -> None:
+            for future in done:
+                results.append(future.result())
+
+        with ThreadPoolExecutor(max_workers=concurrency, thread_name_prefix="ark-upload") as pool:
+            for raw_part in raw_parts:
+                if not isinstance(raw_part, Mapping):
+                    raise ArkError("INTERNAL_ERROR", "Ark returned an invalid multipart part")
+                while len(pending) >= concurrency:
+                    done, pending = wait(pending, return_when=FIRST_COMPLETED)
+                    collect(done)
+                part_number = int(raw_part["partNumber"])
+                start = (part_number - 1) * part_size
+                expected = min(part_size, source.size - start)
+                if expected <= 0:
+                    raise ArkError("INTERNAL_ERROR", "Multipart session exceeds upload size")
+                content: bytes | Any
+                if source.path is not None:
+                    content = iter_file_range(source.path, start, expected)
+                else:
+                    content = read_exact(cast(BinaryIO, source.stream), expected)
+                pending.add(
+                    pool.submit(
+                        self._put_part,
+                        str(raw_part["url"]),
+                        content,
+                        expected,
+                        part_number,
+                    )
+                )
+            if source.stream is not None:
+                ensure_stream_complete(source.stream, source.size)
+            collect(pending)
+        return sorted_parts(results)
+
+    def _put_part(
+        self,
+        url: str,
+        content: Any,
+        size: int,
+        part_number: int,
+    ) -> dict[str, object]:
+        response = self._put(
+            url,
+            content,
+            headers={"content-length": str(size)},
+            part_number=part_number,
+        )
+        etag = response.headers.get("etag", "").replace('"', "")
+        if not etag:
+            raise ArkError("UPLOAD_FAILED", f"Part {part_number} did not return an ETag")
+        return {"partNumber": part_number, "etag": etag}
+
+    def _put(
+        self,
+        url: str,
+        content: Any,
+        *,
+        headers: Mapping[str, str],
+        part_number: int | None = None,
+    ) -> httpx.Response:
+        try:
+            response = self._ark._client.put(url, content=content, headers=headers)
+        except httpx.HTTPError as error:
+            raise network_error(error) from error
+        if response.is_error:
+            raise upload_error(response.status_code, part_number=part_number)
+        return response
+
+
+class Folders:
+    def __init__(self, ark: Ark) -> None:
+        self._ark = ark
+
+    def list(self, *, parent_id: str | None = None) -> tuple[ArkFolder, ...]:
+        value = self._ark._request("GET", f"/folders{query_string({'parentId': parent_id})}")
+        raw_data = value.get("data")
+        return tuple(
+            ArkFolder.from_dict(item)
+            for item in (raw_data if isinstance(raw_data, list) else [])
+            if isinstance(item, Mapping)
+        )
+
+    def create(self, name: str, *, parent_id: str | None = None) -> ArkFolder:
+        payload: dict[str, Any] = {"name": name}
+        if parent_id is not None:
+            payload["parentId"] = parent_id
+        return ArkFolder.from_dict(self._ark._request("POST", "/folders", json=payload))
+
+    def rename(self, folder_id: str, name: str) -> ArkFolder:
+        return ArkFolder.from_dict(
+            self._ark._request(
+                "PATCH",
+                f"/folders/{segment(folder_id)}",
+                json={"name": name},
+            )
+        )
+
+
+class Images:
+    def __init__(self, ark: Ark) -> None:
+        self._ark = ark
+
+    def url(self, asset_id: str, options: ImageOptions | None = None) -> str:
+        return image_url(
+            self._ark._base_url,
+            self._ark._version,
+            asset_id,
+            options or ImageOptions(),
+        )
+
+    def signed_url(self, asset_id: str, *, expires_in_seconds: int | None = None) -> str:
+        suffix = query_string({"ttl": expires_in_seconds})
+        value = self._ark._request(
+            "GET",
+            f"/assets/{segment(asset_id)}/signed-url{suffix}",
+        )
+        return str(value["url"])
+
+
+class Imports:
+    def __init__(self, ark: Ark) -> None:
+        self._ark = ark
+
+    def create(self, input: Mapping[str, Any]) -> dict[str, Any]:
+        return self._ark._request("POST", "/imports", json=input)
+
+    def get(self, import_id: str) -> dict[str, Any]:
+        return self._ark._request("GET", f"/imports/{segment(import_id)}")
+
+    def cancel(self, import_id: str) -> bool:
+        value = self._ark._request("POST", f"/imports/{segment(import_id)}/cancel", json={})
+        return bool(value.get("cancelled"))