licos-platform-sdk 0.1.0__tar.gz

licos_platform_sdk-0.1.0/.gitignore

@@ -0,0 +1,44 @@
+# Rust
+/target/
+**/*.rs.bk
+Cargo.lock
+
+# Node
+node_modules/
+packages/*/dist/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.local
+
+# Workspace
+/workspace/
+
+# Test runtime data
+/test/licos-data/
+/test/screenshots/
+/test/vue-app/
+
+# Build
+*.log
+.licos
+
+/tmp
+
+/Docs/hermes-agent
+/Docs/OpenCode
+/Docs/平台API
+
+*.codex-*
+
+project-20260423_130440

licos_platform_sdk-0.1.0/PKG-INFO

@@ -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/pyproject.toml

@@ -0,0 +1,13 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "licos-platform-sdk"
+version = "0.1.0"
+description = "LICOS platform SDK for storage upload, download, and preview"
+requires-python = ">=3.10"
+dependencies = []
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/licos_platform_sdk"]

licos_platform_sdk-0.1.0/src/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-0.1.0/src/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/tests/test_storage.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+import threading
+import unittest
+from contextlib import contextmanager
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+import sys
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from licos_platform_sdk import download, download_url, preview_url, upload_project
+
+
+class _TestHandler(BaseHTTPRequestHandler):
+    server_version = "licos-platform-sdk-test"
+    protocol_version = "HTTP/1.1"
+
+    def log_message(self, format: str, *args) -> None:  # noqa: A003
+        return
+
+    def do_POST(self) -> None:  # noqa: N802
+        length = int(self.headers.get("Content-Length", "0"))
+        body = self.rfile.read(length)
+        self.server.last_request = {
+            "method": "POST",
+            "path": self.path,
+            "authorization": self.headers.get("Authorization"),
+            "content_type": self.headers.get("Content-Type"),
+            "body": body,
+        }
+        payload = {
+            "code": 0,
+            "message": "ok",
+            "data": {
+                "bucket": "user-demo-project",
+                "object_key": "2026/04/20/uuid/report.txt",
+                "file_name": "report.txt",
+                "content_type": "text/plain",
+                "size_bytes": 11,
+                "preview_url": "http://preview.local/file",
+                "download_url": "http://preview.local/file?download=1",
+            },
+        }
+        raw = json.dumps(payload).encode("utf-8")
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(raw)))
+        self.end_headers()
+        self.wfile.write(raw)
+
+    def do_GET(self) -> None:  # noqa: N802
+        if self.path == "/public/file.txt":
+            self.server.last_request = {
+                "method": "GET",
+                "path": self.path,
+                "authorization": self.headers.get("Authorization"),
+            }
+            body = b"hello world"
+            self.send_response(200)
+            self.send_header("Content-Type", "text/plain")
+            self.send_header("Content-Length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+            return
+        self.send_error(404)
+
+
+@contextmanager
+def _temporary_env(values: dict[str, str]):
+    previous = {key: os.environ.get(key) for key in values}
+    os.environ.update(values)
+    try:
+        yield
+    finally:
+        for key, value in previous.items():
+            if value is None:
+                os.environ.pop(key, None)
+            else:
+                os.environ[key] = value
+
+
+class StorageSdkTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.server = ThreadingHTTPServer(("127.0.0.1", 0), _TestHandler)
+        self.thread = threading.Thread(target=self.server.serve_forever, daemon=True)
+        self.thread.start()
+        self.base_url = f"http://127.0.0.1:{self.server.server_port}"
+
+    def tearDown(self) -> None:
+        self.server.shutdown()
+        self.thread.join(timeout=5)
+        self.server.server_close()
+
+    def test_preview_and_download_url_helpers(self) -> None:
+        self.assertEqual(
+            preview_url(
+                "user-bucket",
+                "2026/04/20/report final.txt",
+                base_url="http://platform.local/",
+            ),
+            "http://platform.local/api/v1/public/storage/user-bucket/2026/04/20/report%20final.txt",
+        )
+        self.assertEqual(
+            download_url("user-bucket", "folder/a.txt", base_url="http://platform.local"),
+            "http://platform.local/api/v1/public/storage/user-bucket/folder/a.txt?download=1",
+        )
+
+    def test_upload_project_uses_env_identity_and_bearer_token(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            file_path = Path(tmp_dir) / "report.txt"
+            file_path.write_text("hello world", encoding="utf-8")
+
+            with _temporary_env(
+                {
+                    "LICOS_ORCHESTRATOR_API_BASE_URL": self.base_url,
+                    "LICOS_USER_TOKEN": "jwt-token",
+                    "LICOS_USER_ID": "demo-user",
+                    "LICOS_PROJECT_ID": "demo-project",
+                }
+            ):
+                result = upload_project(file_path)
+
+        self.assertEqual(result.bucket, "user-demo-project")
+        self.assertEqual(
+            self.server.last_request["path"],
+            "/api/v1/storage/upload/project/demo-user/demo-project",
+        )
+        self.assertEqual(self.server.last_request["authorization"], "Bearer jwt-token")
+        self.assertIn(b'filename="report.txt"', self.server.last_request["body"])
+        self.assertIn(b"hello world", self.server.last_request["body"])
+
+    def test_download_writes_file_content(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            output = Path(tmp_dir) / "downloaded.txt"
+            saved_path = download(
+                f"{self.base_url}/public/file.txt",
+                output,
+                token="jwt-token",
+            )
+
+            self.assertEqual(saved_path, output)
+            self.assertEqual(output.read_text(encoding="utf-8"), "hello world")
+            self.assertEqual(self.server.last_request["authorization"], "Bearer jwt-token")
+
+
+if __name__ == "__main__":
+    unittest.main()