phala-cloud 0.1.1__tar.gz

phala_cloud-0.1.1/.gitignore

@@ -0,0 +1 @@
+.env.test

phala_cloud-0.1.1/Makefile

@@ -0,0 +1,23 @@
+PYTHONPATH ?= src
+PYTEST ?= python -m pytest
+
+.PHONY: test e2e lint fmt check
+
+lint:
+	ruff check .
+
+fmt:
+	ruff format .
+
+check: fmt lint test
+
+test:
+	PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=$(PYTHONPATH) $(PYTEST) -q -p no:cacheprovider
+
+e2e:
+	@bash -lc 'set -a; [ -f .env.test ] && source .env.test; set +a; \
+	if [ -z "$$PHALA_CLOUD_E2E_BASE_URL" ] || [ -z "$$PHALA_CLOUD_E2E_API_KEY" ]; then \
+		echo "Missing env: PHALA_CLOUD_E2E_BASE_URL / PHALA_CLOUD_E2E_API_KEY"; \
+		exit 1; \
+	fi; \
+	PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=$(PYTHONPATH) $(PYTEST) -m e2e -q'

phala_cloud-0.1.1/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: phala-cloud
+Version: 0.1.1
+Summary: Python SDK for Phala Cloud API (sync/async, pydantic, REPL-friendly)
+Project-URL: Homepage, https://github.com/Phala-Network/phala-cloud
+Project-URL: Repository, https://github.com/Phala-Network/phala-cloud
+Project-URL: Issues, https://github.com/Phala-Network/phala-cloud/issues
+Author: Phala Network
+License: Apache-2.0
+Keywords: cloud,cvm,phala,sdk,tee
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: dstack-sdk>=0.1.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.7.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Phala Cloud Python SDK
+
+Python SDK for Phala Cloud API, aligned with `@phala/cloud` action surface.
+
+## Goals
+
+- Pythonic API (`snake_case`, sync-first REPL experience)
+- Sync + Async parity
+- Pydantic request/response validation
+- Safe calls (`safe_*`) without exceptions
+
+## Installation
+
+```bash
+pip install phala-cloud
+```
+
+## Quickstart
+
+### Sync
+
+```python
+from phala_cloud import create_client
+
+client = create_client(api_key="<api-key>")
+me = client.get_current_user()
+print(me.model_dump())
+```
+
+### Async
+
+```python
+import asyncio
+from phala_cloud import create_async_client
+
+
+async def main() -> None:
+    client = create_async_client(api_key="<api-key>")
+    me = await client.get_current_user()
+    print(me.model_dump())
+    await client.aclose()
+
+
+asyncio.run(main())
+```
+
+## Configuration
+
+### Environment variables
+
+- `PHALA_CLOUD_API_KEY`
+- `PHALA_CLOUD_API_PREFIX` (e.g. `https://cloud-api.phala.com/api/v1`)
+
+### Client options
+
+- `api_key`
+- `base_url`
+- `version` (`2025-10-28` / `2026-01-21`)
+- `timeout`
+- `headers`
+- `use_cookie_auth`
+
+## API Style
+
+- Direct methods: raise on HTTP/validation errors
+- Safe methods (`safe_*`): return `SafeResult`
+- Function-style wrappers available in `phala_cloud.actions`
+
+Example:
+
+```python
+result = client.safe_get_kms_list()
+if result.ok:
+    print(result.data.items)
+else:
+    print(result.error)
+```
+
+## E2E Test (full interface matrix)
+
+E2E only needs two variables:
+
+- `PHALA_CLOUD_E2E_BASE_URL`
+- `PHALA_CLOUD_E2E_API_KEY`
+
+It covers sync + async, direct + safe styles, and full interface paths.
+
+### Run
+
+```bash
+cd python
+PHALA_CLOUD_E2E_BASE_URL="https://<your-test-api>/api/v1" \
+PHALA_CLOUD_E2E_API_KEY="<api-key>" \
+make e2e
+```
+
+Or put them in `python/.env.test`:
+
+```dotenv
+PHALA_CLOUD_E2E_BASE_URL=https://<your-test-api>/api/v1
+PHALA_CLOUD_E2E_API_KEY=<api-key>
+```
+
+Then simply:
+
+```bash
+cd python
+make e2e
+```
+
+## Development
+
+```bash
+cd python
+make test
+```
+
+## License
+
+Apache-2.0

phala_cloud-0.1.1/README.md

@@ -0,0 +1,120 @@
+# Phala Cloud Python SDK
+
+Python SDK for Phala Cloud API, aligned with `@phala/cloud` action surface.
+
+## Goals
+
+- Pythonic API (`snake_case`, sync-first REPL experience)
+- Sync + Async parity
+- Pydantic request/response validation
+- Safe calls (`safe_*`) without exceptions
+
+## Installation
+
+```bash
+pip install phala-cloud
+```
+
+## Quickstart
+
+### Sync
+
+```python
+from phala_cloud import create_client
+
+client = create_client(api_key="<api-key>")
+me = client.get_current_user()
+print(me.model_dump())
+```
+
+### Async
+
+```python
+import asyncio
+from phala_cloud import create_async_client
+
+
+async def main() -> None:
+    client = create_async_client(api_key="<api-key>")
+    me = await client.get_current_user()
+    print(me.model_dump())
+    await client.aclose()
+
+
+asyncio.run(main())
+```
+
+## Configuration
+
+### Environment variables
+
+- `PHALA_CLOUD_API_KEY`
+- `PHALA_CLOUD_API_PREFIX` (e.g. `https://cloud-api.phala.com/api/v1`)
+
+### Client options
+
+- `api_key`
+- `base_url`
+- `version` (`2025-10-28` / `2026-01-21`)
+- `timeout`
+- `headers`
+- `use_cookie_auth`
+
+## API Style
+
+- Direct methods: raise on HTTP/validation errors
+- Safe methods (`safe_*`): return `SafeResult`
+- Function-style wrappers available in `phala_cloud.actions`
+
+Example:
+
+```python
+result = client.safe_get_kms_list()
+if result.ok:
+    print(result.data.items)
+else:
+    print(result.error)
+```
+
+## E2E Test (full interface matrix)
+
+E2E only needs two variables:
+
+- `PHALA_CLOUD_E2E_BASE_URL`
+- `PHALA_CLOUD_E2E_API_KEY`
+
+It covers sync + async, direct + safe styles, and full interface paths.
+
+### Run
+
+```bash
+cd python
+PHALA_CLOUD_E2E_BASE_URL="https://<your-test-api>/api/v1" \
+PHALA_CLOUD_E2E_API_KEY="<api-key>" \
+make e2e
+```
+
+Or put them in `python/.env.test`:
+
+```dotenv
+PHALA_CLOUD_E2E_BASE_URL=https://<your-test-api>/api/v1
+PHALA_CLOUD_E2E_API_KEY=<api-key>
+```
+
+Then simply:
+
+```bash
+cd python
+make e2e
+```
+
+## Development
+
+```bash
+cd python
+make test
+```
+
+## License
+
+Apache-2.0

phala_cloud-0.1.1/examples/repl.py

@@ -0,0 +1,14 @@
+from phala_cloud import create_client
+
+client = create_client()
+
+me = client.safe_get_current_user()
+if me.ok:
+    print("Current user:")
+    print(me.data)
+else:
+    print(f"Error: {me.error}")
+
+nodes = client.safe_get_available_nodes()
+if nodes.ok and nodes.data:
+    print(f"Available nodes: {len(nodes.data.nodes)}")

phala_cloud-0.1.1/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["hatchling>=1.25.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "phala-cloud"
+version = "0.1.1"
+description = "Python SDK for Phala Cloud API (sync/async, pydantic, REPL-friendly)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Phala Network" }]
+keywords = ["phala", "cloud", "sdk", "tee", "cvm"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "httpx>=0.27.0",
+  "pydantic>=2.7.0",
+  "dstack-sdk>=0.1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0.0",
+  "pytest-asyncio>=0.23.0",
+  "ruff>=0.6.0",
+  "mypy>=1.10.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Phala-Network/phala-cloud"
+Repository = "https://github.com/Phala-Network/phala-cloud"
+Issues = "https://github.com/Phala-Network/phala-cloud/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/phala_cloud"]
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+markers = [
+  "e2e: end-to-end tests against real API base URL",
+]

phala_cloud-0.1.1/src/phala_cloud/__init__.py

@@ -0,0 +1,36 @@
+from .actions import *  # noqa: F403
+from .blockchains import add_compose_hash, deploy_app_auth
+from .client import DEFAULT_API_VERSION, SUPPORTED_API_VERSIONS, ApiVersion
+from .errors import ApiError, PhalaCloudError, RequestError, ValidationError
+from .full_client import AsyncPhalaCloud, PhalaCloud, create_async_client, create_client
+from .models import *  # noqa: F403
+from .result import SafeResult
+from .utils import (
+    encrypt_env_vars,
+    get_compose_hash,
+    parse_env,
+    parse_env_vars,
+    verify_env_encrypt_public_key,
+)
+
+__all__ = [
+    "ApiError",
+    "ApiVersion",
+    "AsyncPhalaCloud",
+    "DEFAULT_API_VERSION",
+    "PhalaCloud",
+    "PhalaCloudError",
+    "RequestError",
+    "SUPPORTED_API_VERSIONS",
+    "SafeResult",
+    "ValidationError",
+    "add_compose_hash",
+    "deploy_app_auth",
+    "encrypt_env_vars",
+    "get_compose_hash",
+    "parse_env",
+    "parse_env_vars",
+    "verify_env_encrypt_public_key",
+    "create_async_client",
+    "create_client",
+]

phala_cloud-0.1.1/src/phala_cloud/action_responses.py

@@ -0,0 +1,222 @@
+from __future__ import annotations
+
+from pydantic import Field
+
+from .models.auth import CurrentUserV20251028, CurrentUserV20260121
+from .models.base import CloudModel
+from .models.cvms import PaginatedCvmInfosV20251028, PaginatedCvmInfosV20260121
+
+
+class GenericObject(CloudModel):
+    pass
+
+
+class WorkspaceResponse(CloudModel):
+    id: str
+    name: str
+    slug: str | None = None
+    tier: str | None = None
+    role: str | None = None
+
+
+class ListWorkspacesResponse(CloudModel):
+    data: list[WorkspaceResponse] = Field(default_factory=list)
+    pagination: GenericObject | None = None
+
+
+class InstanceTypesAllResponse(CloudModel):
+    result: list[GenericObject] = Field(default_factory=list)
+
+
+class InstanceTypesFamilyResponse(CloudModel):
+    items: list[GenericObject] = Field(default_factory=list)
+    total: int | None = None
+    family: str | None = None
+
+
+class ProvisionCvmResponse(CloudModel):
+    app_id: str | None = None
+    app_env_encrypt_pubkey: str | None = None
+    compose_hash: str
+    kms_info: GenericObject | None = None
+    fmspc: str | None = None
+    device_id: str | None = None
+    os_image_hash: str | None = None
+    instance_type: str | None = None
+    node_id: int | None = None
+    kms_id: str | None = None
+
+
+class CommitCvmProvisionResponse(CloudModel):
+    id: int | str
+    name: str
+    status: str
+
+
+class ComposeHashPreconditionResponse(CloudModel):
+    status: str = "precondition_required"
+    message: str
+    compose_hash: str
+    app_id: str
+    device_id: str
+    kms_info: GenericObject | None = None
+
+
+class InProgressResponse(CloudModel):
+    status: str = "in_progress"
+    message: str | None = None
+    correlation_id: str | None = None
+
+
+class CvmStateResponse(CloudModel):
+    id: str | None = None
+    instance_id: str | None = None
+    name: str | None = None
+    status: str
+
+
+class AppFilterOptionsResponse(CloudModel):
+    statuses: list[str] = Field(default_factory=list)
+    image_versions: list[str] = Field(default_factory=list)
+    instance_types: list[str] = Field(default_factory=list)
+    kms_slugs: list[str] = Field(default_factory=list)
+    kms_types: list[str] = Field(default_factory=list)
+    regions: list[str] = Field(default_factory=list)
+    nodes: list[str] = Field(default_factory=list)
+
+
+class SshKeyResponse(CloudModel):
+    id: str
+    name: str
+    public_key: str
+
+
+class ImportGithubProfileResponse(CloudModel):
+    github_username: str
+    keys_added: int
+    keys_skipped: int
+    errors: list[str] = Field(default_factory=list)
+
+
+class SyncGithubSshKeysResponse(CloudModel):
+    synced_count: int
+    keys_added: int
+    keys_updated: int
+    keys_removed: int
+    errors: list[str] = Field(default_factory=list)
+
+
+class AppEnvPubkeyResponse(CloudModel):
+    public_key: str
+    signature: str
+
+
+class NextAppIdsResponse(CloudModel):
+    app_ids: list[GenericObject] = Field(default_factory=list)
+
+
+class WorkspaceNodesResponse(CloudModel):
+    items: list[GenericObject] = Field(default_factory=list)
+    total: int | None = None
+    page: int | None = None
+    page_size: int | None = None
+    pages: int | None = None
+
+
+class WorkspaceQuotasResponse(CloudModel):
+    team_slug: str | None = None
+    tier: str | None = None
+    quotas: GenericObject | None = None
+    reserved_nodes: GenericObject | None = None
+    reserved_gpu: GenericObject | None = None
+    as_of: str | None = None
+
+
+class CvmInfoResponse(CloudModel):
+    id: str | int | None = None
+    name: str | None = None
+    status: str | None = None
+
+
+class ComposeFileResponse(CloudModel):
+    docker_compose_file: str | None = None
+
+
+class CvmActionResponse(CloudModel):
+    id: int | str | None = None
+    name: str | None = None
+    status: str | None = None
+
+
+class CvmStatsResponse(CloudModel):
+    is_online: bool | None = None
+    status: str | None = None
+
+
+class CvmNetworkResponse(CloudModel):
+    is_online: bool | None = None
+
+
+class CvmContainersResponse(CloudModel):
+    is_online: bool | None = None
+
+
+class CvmAttestationResponse(CloudModel):
+    is_online: bool | None = None
+
+
+class CvmVisibilityResponse(CloudModel):
+    status: str | None = None
+
+
+class CvmUserConfigResponse(CloudModel):
+    hostname: str | None = None
+    ssh_authorized_keys: list[str] = Field(default_factory=list)
+
+
+class RefreshInstanceIdResponse(CloudModel):
+    status: str | None = None
+
+
+class RefreshInstanceIdsResponse(CloudModel):
+    total: int
+    scanned: int
+    updated: int
+    unchanged: int
+    skipped: int
+    conflicts: int
+    errors: int
+    items: list[GenericObject] = Field(default_factory=list)
+
+
+class AppListResponse(CloudModel):
+    items: list[GenericObject] = Field(default_factory=list)
+    total: int | None = None
+    page: int | None = None
+    page_size: int | None = None
+    pages: int | None = None
+
+
+class AppInfoResponse(CloudModel):
+    id: str | None = None
+    name: str | None = None
+
+
+class AppRevisionsResponse(CloudModel):
+    items: list[GenericObject] = Field(default_factory=list)
+    total: int | None = None
+    page: int | None = None
+    page_size: int | None = None
+    pages: int | None = None
+
+
+class AppRevisionDetailResponse(CloudModel):
+    id: str | None = None
+
+
+class AppAttestationResponse(CloudModel):
+    instances: list[GenericObject] = Field(default_factory=list)
+
+
+CurrentUserResponse = CurrentUserV20260121 | CurrentUserV20251028
+PaginatedCvmListResponse = PaginatedCvmInfosV20260121 | PaginatedCvmInfosV20251028