licos-platform-sdk 0.1.0__py3-none-any.whl

licos_platform_sdk/__init__.py

@@ -0,0 +1,25 @@
+from .storage import (
+    ApiError,
+    ConfigurationError,
+    PlatformSdkError,
+    StorageClient,
+    UploadResult,
+    download,
+    download_url,
+    preview_url,
+    upload_project,
+    upload_user,
+)
+
+__all__ = [
+    "ApiError",
+    "ConfigurationError",
+    "PlatformSdkError",
+    "StorageClient",
+    "UploadResult",
+    "download",
+    "download_url",
+    "preview_url",
+    "upload_project",
+    "upload_user",
+]

licos_platform_sdk/storage.py

@@ -0,0 +1,323 @@
+from __future__ import annotations
+
+import json
+import mimetypes
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+
+
+class PlatformSdkError(RuntimeError):
+    """Base SDK error."""
+
+
+class ConfigurationError(PlatformSdkError):
+    """Raised when required runtime configuration is missing."""
+
+
+class ApiError(PlatformSdkError):
+    """Raised when the platform API returns an error."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int | None = None,
+        code: int | None = None,
+        details: Any | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.details = details
+
+
+@dataclass(slots=True)
+class UploadResult:
+    bucket: str
+    object_key: str
+    file_name: str
+    content_type: str
+    size_bytes: int
+    preview_url: str
+    download_url: str
+
+    @classmethod
+    def from_dict(cls, payload: dict[str, Any]) -> "UploadResult":
+        return cls(
+            bucket=str(payload["bucket"]),
+            object_key=str(payload["object_key"]),
+            file_name=str(payload["file_name"]),
+            content_type=str(payload["content_type"]),
+            size_bytes=int(payload["size_bytes"]),
+            preview_url=str(payload["preview_url"]),
+            download_url=str(payload["download_url"]),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def _require_env(name: str) -> str:
+    value = os.environ.get(name)
+    if value:
+        return value
+    raise ConfigurationError(f"Missing required environment variable: {name}")
+
+
+def _normalize_base_url(base_url: str | None) -> str:
+    value = base_url or os.environ.get("LICOS_ORCHESTRATOR_API_BASE_URL")
+    if not value:
+        raise ConfigurationError(
+            "Missing required environment variable: LICOS_ORCHESTRATOR_API_BASE_URL"
+        )
+    return value.rstrip("/")
+
+
+def _resolve_token(token: str | None) -> str:
+    return token or _require_env("LICOS_USER_TOKEN")
+
+
+def _resolve_user_id(user_id: str | None) -> str:
+    return user_id or _require_env("LICOS_USER_ID")
+
+
+def _resolve_project_id(project_id: str | None) -> str:
+    return project_id or _require_env("LICOS_PROJECT_ID")
+
+
+def _quote_storage_path_segment(value: str) -> str:
+    return urllib.parse.quote(value, safe="")
+
+
+def _quote_object_key(value: str) -> str:
+    return "/".join(_quote_storage_path_segment(part) for part in value.split("/"))
+
+
+def _guess_content_type(file_path: Path) -> str:
+    guessed, _ = mimetypes.guess_type(file_path.name)
+    return guessed or "application/octet-stream"
+
+
+def _encode_multipart(file_path: Path, file_bytes: bytes, content_type: str) -> tuple[bytes, str]:
+    boundary = f"----LICOSBoundary{uuid4().hex}"
+    disposition = (
+        f'Content-Disposition: form-data; name="file"; filename="{file_path.name}"\r\n'
+    )
+    payload = b"".join(
+        [
+            f"--{boundary}\r\n".encode("utf-8"),
+            disposition.encode("utf-8"),
+            f"Content-Type: {content_type}\r\n\r\n".encode("utf-8"),
+            file_bytes,
+            b"\r\n",
+            f"--{boundary}--\r\n".encode("utf-8"),
+        ]
+    )
+    return payload, boundary
+
+
+class StorageClient:
+    def __init__(
+        self,
+        *,
+        base_url: str | None = None,
+        token: str | None = None,
+        user_id: str | None = None,
+        project_id: str | None = None,
+        timeout: int = 60,
+        opener: urllib.request.OpenerDirector | None = None,
+    ) -> None:
+        self.base_url = base_url
+        self.token = token
+        self.user_id = user_id
+        self.project_id = project_id
+        self.timeout = timeout
+        self._opener = opener or urllib.request.build_opener()
+
+    def preview_url(self, bucket: str, object_key: str) -> str:
+        base = _normalize_base_url(self.base_url)
+        return (
+            f"{base}/api/v1/public/storage/"
+            f"{_quote_storage_path_segment(bucket)}/{_quote_object_key(object_key)}"
+        )
+
+    def download_url(self, bucket: str, object_key: str) -> str:
+        return f"{self.preview_url(bucket, object_key)}?download=1"
+
+    def upload_user(self, file_path: str | os.PathLike[str]) -> UploadResult:
+        base = _normalize_base_url(self.base_url)
+        return self._upload(
+            f"{base}/api/v1/storage/upload/user",
+            file_path=file_path,
+        )
+
+    def upload_project(
+        self,
+        file_path: str | os.PathLike[str],
+        *,
+        project_id: str | None = None,
+        user_id: str | None = None,
+    ) -> UploadResult:
+        base = _normalize_base_url(self.base_url)
+        resolved_user_id = _resolve_user_id(user_id or self.user_id)
+        resolved_project_id = _resolve_project_id(project_id or self.project_id)
+        return self._upload(
+            (
+                f"{base}/api/v1/storage/upload/project/"
+                f"{_quote_storage_path_segment(resolved_user_id)}/"
+                f"{_quote_storage_path_segment(resolved_project_id)}"
+            ),
+            file_path=file_path,
+        )
+
+    def download(
+        self,
+        url: str,
+        output_path: str | os.PathLike[str],
+    ) -> Path:
+        request = urllib.request.Request(
+            url,
+            method="GET",
+            headers={
+                "Authorization": f"Bearer {_resolve_token(self.token)}",
+            },
+        )
+        try:
+            with self._opener.open(request, timeout=self.timeout) as response:
+                payload = response.read()
+        except urllib.error.HTTPError as exc:
+            details = exc.read().decode("utf-8", errors="replace")
+            raise ApiError(
+                f"Platform download failed: HTTP {exc.code}",
+                status=exc.code,
+                details=details,
+            ) from exc
+
+        output = Path(output_path)
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_bytes(payload)
+        return output
+
+    def _upload(self, url: str, *, file_path: str | os.PathLike[str]) -> UploadResult:
+        path = Path(file_path)
+        file_bytes = path.read_bytes()
+        content_type = _guess_content_type(path)
+        body, boundary = _encode_multipart(path, file_bytes, content_type)
+        request = urllib.request.Request(
+            url,
+            data=body,
+            method="POST",
+            headers={
+                "Authorization": f"Bearer {_resolve_token(self.token)}",
+                "Content-Type": f"multipart/form-data; boundary={boundary}",
+                "Accept": "application/json",
+            },
+        )
+        payload = self._request_json(request)
+        return UploadResult.from_dict(payload)
+
+    def _request_json(self, request: urllib.request.Request) -> dict[str, Any]:
+        try:
+            with self._opener.open(request, timeout=self.timeout) as response:
+                body = response.read().decode("utf-8")
+                status = response.status
+        except urllib.error.HTTPError as exc:
+            body = exc.read().decode("utf-8", errors="replace")
+            payload = _parse_json(body)
+            raise ApiError(
+                _extract_message(payload, fallback=f"Platform API failed: HTTP {exc.code}"),
+                status=exc.code,
+                code=_extract_code(payload),
+                details=_extract_details(payload),
+            ) from exc
+
+        payload = _parse_json(body)
+        code = _extract_code(payload)
+        if status >= 400 or code != 0:
+            raise ApiError(
+                _extract_message(payload, fallback=f"Platform API failed: HTTP {status}"),
+                status=status,
+                code=code,
+                details=_extract_details(payload),
+            )
+        data = payload.get("data")
+        if not isinstance(data, dict):
+            raise ApiError("Platform API returned invalid data payload", status=status, code=code)
+        return data
+
+
+def _parse_json(raw: str) -> dict[str, Any]:
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise ApiError("Platform API returned non-JSON response", details=raw) from exc
+    if not isinstance(payload, dict):
+        raise ApiError("Platform API returned invalid JSON envelope", details=payload)
+    return payload
+
+
+def _extract_code(payload: dict[str, Any]) -> int | None:
+    value = payload.get("code")
+    return int(value) if isinstance(value, (int, float)) else None
+
+
+def _extract_message(payload: dict[str, Any], *, fallback: str) -> str:
+    value = payload.get("message")
+    return value if isinstance(value, str) and value else fallback
+
+
+def _extract_details(payload: dict[str, Any]) -> Any:
+    return payload.get("data", payload)
+
+
+def _default_client(**kwargs: Any) -> StorageClient:
+    return StorageClient(**kwargs)
+
+
+def preview_url(bucket: str, object_key: str, *, base_url: str | None = None) -> str:
+    return _default_client(base_url=base_url).preview_url(bucket, object_key)
+
+
+def download_url(bucket: str, object_key: str, *, base_url: str | None = None) -> str:
+    return _default_client(base_url=base_url).download_url(bucket, object_key)
+
+
+def upload_user(
+    file_path: str | os.PathLike[str],
+    *,
+    base_url: str | None = None,
+    token: str | None = None,
+) -> UploadResult:
+    return _default_client(base_url=base_url, token=token).upload_user(file_path)
+
+
+def upload_project(
+    file_path: str | os.PathLike[str],
+    *,
+    base_url: str | None = None,
+    token: str | None = None,
+    project_id: str | None = None,
+    user_id: str | None = None,
+) -> UploadResult:
+    return _default_client(
+        base_url=base_url,
+        token=token,
+        project_id=project_id,
+        user_id=user_id,
+    ).upload_project(file_path)
+
+
+def download(
+    url: str,
+    output_path: str | os.PathLike[str],
+    *,
+    base_url: str | None = None,
+    token: str | None = None,
+) -> Path:
+    return _default_client(base_url=base_url, token=token).download(url, output_path)

licos_platform_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,5 @@
+Metadata-Version: 2.4
+Name: licos-platform-sdk
+Version: 0.1.0
+Summary: LICOS platform SDK for storage upload, download, and preview
+Requires-Python: >=3.10

licos_platform_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+licos_platform_sdk/__init__.py,sha256=REJ7rkegRgkM-VZEIeOsrBoUO19ibMZ6RAAFfsorGAo,426
+licos_platform_sdk/storage.py,sha256=kcnQfJwoItcgv_SEzy_VfIuZUKhxolbVG7BESPqSg-Y,10150
+licos_platform_sdk-0.1.0.dist-info/METADATA,sha256=eVFVvfD4AeCgxscPElsme7dW5pxG0nv7QrTu6ZP8QRE,156
+licos_platform_sdk-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+licos_platform_sdk-0.1.0.dist-info/RECORD,,

licos_platform_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any