lumilake-sdk 0.1.0.dev1__py3-none-any.whl

lumilake/__init__.py

@@ -0,0 +1,57 @@
+"""Lumilake Python SDK.
+
+Programmatic equivalent of the ``lumilake`` CLI. Every CLI subcommand has a
+matching method on ``LumilakeClient`` / ``AsyncLumilakeClient``.
+
+    from lumilake import LumilakeClient, AsyncLumilakeClient
+    with LumilakeClient.from_config() as client:
+        client.jobs.list()
+"""
+
+import logging
+
+from lumilake._base_client import BaseAsyncClient, BaseClient, unwrap
+from lumilake.async_client import AsyncLumilakeClient
+from lumilake.client import LumilakeClient
+from lumilake.config import DEFAULT_CONFIG_PATH, LumilakeConfig
+from lumilake.errors import (
+    DeployError,
+    HttpError,
+    LumilakeError,
+    NotFoundError,
+)
+from lumilake.resources.deploy import SERVICE_NAMES, AsyncDeploy, Deploy
+from lumilake.resources.info import AsyncInfo, Info
+from lumilake.resources.jobs import AsyncJobs, Jobs
+from lumilake.resources.traces import AsyncTraces, Traces
+from lumilake.resources.workers import AsyncWorkers, Workers
+
+__version__ = "0.1.0.dev1"
+
+logging.getLogger("httpx").setLevel(logging.WARNING)
+logging.getLogger("httpcore").setLevel(logging.WARNING)
+
+__all__ = [
+    "DEFAULT_CONFIG_PATH",
+    "SERVICE_NAMES",
+    "AsyncDeploy",
+    "AsyncInfo",
+    "AsyncJobs",
+    "AsyncLumilakeClient",
+    "AsyncTraces",
+    "AsyncWorkers",
+    "BaseAsyncClient",
+    "BaseClient",
+    "Deploy",
+    "DeployError",
+    "HttpError",
+    "Info",
+    "Jobs",
+    "LumilakeClient",
+    "LumilakeConfig",
+    "LumilakeError",
+    "NotFoundError",
+    "Traces",
+    "Workers",
+    "unwrap",
+]

lumilake/_base_client.py

@@ -0,0 +1,202 @@
+"""Shared HTTP transport for the SDK.
+
+Two parallel classes — ``BaseClient`` for sync, ``BaseAsyncClient`` for async —
+own the connection lifecycle, version-prefix handling (``/api/v1``), default
+headers, and error → exception mapping (404 → ``NotFoundError``, 5xx →
+``HttpError``). Resource classes consume them via
+``self._client.get/post/...`` and call ``unwrap()`` on the response.
+"""
+
+import logging
+from collections.abc import Mapping
+from typing import Any, Self
+
+import httpx
+from lumilake import envs
+from lumilake.config import LumilakeConfig
+from lumilake.errors import HttpError, NotFoundError
+
+logger = logging.getLogger(__name__)
+
+API_VERSION_PREFIX = "/api/v1"
+DEFAULT_TIMEOUT = 300.0
+
+
+def _resolve_timeout(timeout: float | None) -> float:
+    if timeout is not None and timeout > 0:
+        return timeout
+    return envs.get_lumilake_timeout(default=DEFAULT_TIMEOUT)
+
+
+def resolve_config(
+    base_url: str | None,
+) -> str:
+    """Resolve the base URL in priority order: explicit arg >
+    ``LUMILAKE_BASE_URL`` env > saved ``~/.lumilake/config.toml``.
+
+    Raises ``RuntimeError`` if no base_url can be determined and no saved
+    config exists — the caller should run ``lumilake login`` first.
+    """
+    url = base_url or envs.get_lumilake_base_url()
+    if not url:
+        try:
+            cfg = LumilakeConfig.load()
+        except FileNotFoundError as exc:
+            raise RuntimeError(
+                "no base_url provided and no saved config. Pass base_url= "
+                "explicitly, set LUMILAKE_BASE_URL, or run `lumilake login`."
+            ) from exc
+        url = cfg.base_url
+    return url
+
+
+def _headers(extra: Mapping[str, str] | None) -> dict[str, str]:
+    headers: dict[str, str] = {"Accept": "application/json"}
+    if extra:
+        headers.update(extra)
+    return headers
+
+
+def _url(base_url: str, path: str, *, version_prefix: bool) -> str:
+    p = path if path.startswith("/") else f"/{path}"
+    if version_prefix and not p.startswith(API_VERSION_PREFIX):
+        p = f"{API_VERSION_PREFIX}{p}"
+    return f"{base_url.rstrip('/')}{p}"
+
+
+def _raise_for_status(response: httpx.Response, url: str) -> None:
+    if response.status_code == 404:
+        raise NotFoundError(response.status_code, response.text, url=url)
+    if response.status_code >= 400:
+        raise HttpError(response.status_code, response.text, url=url)
+
+
+def unwrap(response: httpx.Response) -> Any:
+    """Unwrap the ``{"ok": ..., "data": ...}`` envelope used by the lumilake API."""
+    payload = response.json()
+    if isinstance(payload, dict) and "data" in payload:
+        return payload["data"]
+    return payload
+
+
+class BaseClient:
+    """Sync HTTP transport. Wraps ``httpx.Client`` with shared headers,
+    ``/api/v1`` prefixing, and error-to-exception mapping. Owns the
+    underlying client when constructed without an injected one;
+    ``close()`` / ``__exit__`` close it."""
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        timeout: float | None = None,
+        verify: bool | str = True,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self.base_url = base_url
+        self._http = http_client or httpx.Client(
+            timeout=_resolve_timeout(timeout),
+            verify=verify,
+        )
+        self._owns_client = http_client is None
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        version_prefix: bool = True,
+        params: Mapping[str, Any] | None = None,
+        json_body: Any = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> httpx.Response:
+        url = _url(self.base_url, path, version_prefix=version_prefix)
+        try:
+            response = self._http.request(
+                method,
+                url,
+                params=dict(params) if params else None,
+                json=json_body,
+                headers=_headers(headers),
+            )
+        except httpx.HTTPError as exc:
+            raise HttpError(0, f"network: {exc}", url=url) from exc
+        _raise_for_status(response, url)
+        return response
+
+    def get(self, path: str, **kwargs: Any) -> httpx.Response:
+        return self.request("GET", path, **kwargs)
+
+    def post(self, path: str, **kwargs: Any) -> httpx.Response:
+        return self.request("POST", path, **kwargs)
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._http.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+
+class BaseAsyncClient:
+    """Async HTTP transport. Wraps ``httpx.AsyncClient`` with the same path,
+    headers, and error-mapping rules as ``BaseClient``; resources ``await``
+    ``self._client.request(...)`` and call ``unwrap()`` on the response."""
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        timeout: float | None = None,
+        verify: bool | str = True,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.base_url = base_url
+        self._http = http_client or httpx.AsyncClient(
+            timeout=_resolve_timeout(timeout),
+            verify=verify,
+        )
+        self._owns_client = http_client is None
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        version_prefix: bool = True,
+        params: Mapping[str, Any] | None = None,
+        json_body: Any = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> httpx.Response:
+        url = _url(self.base_url, path, version_prefix=version_prefix)
+        try:
+            response = await self._http.request(
+                method,
+                url,
+                params=dict(params) if params else None,
+                json=json_body,
+                headers=_headers(headers),
+            )
+        except httpx.HTTPError as exc:
+            raise HttpError(0, f"network: {exc}", url=url) from exc
+        _raise_for_status(response, url)
+        return response
+
+    async def get(self, path: str, **kwargs: Any) -> httpx.Response:
+        return await self.request("GET", path, **kwargs)
+
+    async def post(self, path: str, **kwargs: Any) -> httpx.Response:
+        return await self.request("POST", path, **kwargs)
+
+    async def close(self) -> None:
+        if self._owns_client:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()

lumilake/async_client.py

@@ -0,0 +1,87 @@
+"""AsyncLumilakeClient — asynchronous SDK entry point.
+
+Composes every async resource — HTTP-backed ones over ``httpx.AsyncClient``,
+``deploy`` over ``asyncio.to_thread`` calls into ``lumilake_deploy``. Same
+construction options as ``LumilakeClient`` (explicit args, env, or
+``.from_config()``).
+"""
+
+import logging
+from pathlib import Path
+from typing import Any, Self
+
+import httpx
+from lumilake._base_client import BaseAsyncClient, resolve_config
+from lumilake.config import LumilakeConfig
+from lumilake.resources.deploy import AsyncDeploy
+from lumilake.resources.info import AsyncInfo
+from lumilake.resources.jobs import AsyncJobs
+from lumilake.resources.traces import AsyncTraces
+from lumilake.resources.workers import AsyncWorkers
+
+logger = logging.getLogger(__name__)
+
+
+class AsyncLumilakeClient(BaseAsyncClient):
+    """Asynchronous Lumilake API client.
+
+    Usage::
+
+        from lumilake import AsyncLumilakeClient
+
+        async with AsyncLumilakeClient(
+            base_url="http://localhost:19000",
+        ) as client:
+            await client.jobs.list()
+            await client.deploy.up()
+
+    Or::
+
+        client = AsyncLumilakeClient.from_config()
+    """
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        *,
+        timeout: float | None = None,
+        verify: bool | str = True,
+        http_client: httpx.AsyncClient | None = None,
+        repo_root: Path | str | None = None,
+    ) -> None:
+        url = resolve_config(base_url)
+        super().__init__(
+            base_url=url,
+            timeout=timeout,
+            verify=verify,
+            http_client=http_client,
+        )
+        self._repo_root = Path(repo_root) if repo_root else Path.cwd()
+
+        self.info = AsyncInfo(self)
+        self.deploy = AsyncDeploy(self._repo_root)
+        self.jobs = AsyncJobs(self)
+        self.workers = AsyncWorkers(self)
+        self.traces = AsyncTraces(self)
+
+    @classmethod
+    def from_config(
+        cls,
+        path: Path | str | None = None,
+        *,
+        timeout: float | None = None,
+        verify: bool | str = True,
+        http_client: httpx.AsyncClient | None = None,
+        repo_root: Path | str | None = None,
+    ) -> Self:
+        config = LumilakeConfig.load(path)
+        return cls(
+            base_url=config.base_url,
+            timeout=timeout,
+            verify=verify,
+            http_client=http_client,
+            repo_root=repo_root,
+        )
+
+    async def health(self) -> dict[str, Any]:
+        return await self.info.health()

lumilake/client.py

@@ -0,0 +1,89 @@
+"""LumilakeClient — synchronous SDK entry point.
+
+Composes every server-API resource (HTTP) plus the ``deploy`` resource
+(subprocess) and exposes them as attributes (``client.jobs``,
+``client.workers``, ``client.deploy``, …). Construct with an explicit
+``base_url``, ``LUMILAKE_BASE_URL`` env var, or
+``LumilakeClient.from_config()`` to read the file ``lumilake login``
+writes.
+"""
+
+import logging
+from pathlib import Path
+from typing import Any, Self
+
+import httpx
+from lumilake._base_client import BaseClient, resolve_config
+from lumilake.config import LumilakeConfig
+from lumilake.resources.deploy import Deploy
+from lumilake.resources.info import Info
+from lumilake.resources.jobs import Jobs
+from lumilake.resources.traces import Traces
+from lumilake.resources.workers import Workers
+
+logger = logging.getLogger(__name__)
+
+
+class LumilakeClient(BaseClient):
+    """Synchronous Lumilake API client.
+
+    Usage::
+
+        from lumilake import LumilakeClient
+
+        with LumilakeClient(base_url="http://localhost:19000") as client:
+            client.jobs.list()
+            client.deploy.up()
+
+    Or pull the URL from ``~/.lumilake/config.toml`` (written by
+    ``lumilake login``)::
+
+        client = LumilakeClient.from_config()
+    """
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        *,
+        timeout: float | None = None,
+        verify: bool | str = True,
+        http_client: httpx.Client | None = None,
+        repo_root: Path | str | None = None,
+    ) -> None:
+        url = resolve_config(base_url)
+        super().__init__(
+            base_url=url,
+            timeout=timeout,
+            verify=verify,
+            http_client=http_client,
+        )
+        self._repo_root = Path(repo_root) if repo_root else Path.cwd()
+
+        self.info = Info(self)
+        self.deploy = Deploy(self._repo_root)
+        self.jobs = Jobs(self)
+        self.workers = Workers(self)
+        self.traces = Traces(self)
+
+    @classmethod
+    def from_config(
+        cls,
+        path: Path | str | None = None,
+        *,
+        timeout: float | None = None,
+        verify: bool | str = True,
+        http_client: httpx.Client | None = None,
+        repo_root: Path | str | None = None,
+    ) -> Self:
+        config = LumilakeConfig.load(path)
+        return cls(
+            base_url=config.base_url,
+            timeout=timeout,
+            verify=verify,
+            http_client=http_client,
+            repo_root=repo_root,
+        )
+
+    def health(self) -> dict[str, Any]:
+        """Shortcut for ``client.info.health()``."""
+        return self.info.health()

lumilake/config.py

@@ -0,0 +1,40 @@
+"""Saved connection state at ``~/.lumilake/config.toml``.
+
+Reads the same TOML schema ``lumilake login`` writes (``base_url``).
+"""
+
+import logging
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_CONFIG_PATH = Path.home() / ".lumilake" / "config.toml"
+
+
+@dataclass
+class LumilakeConfig:
+    """Saved server URL. Matches the CLI's TOML schema."""
+
+    base_url: str
+
+    @classmethod
+    def load(cls, path: Path | str | None = None) -> "LumilakeConfig":
+        """Read ``path`` (default ``~/.lumilake/config.toml``)."""
+        target = Path(path) if path else DEFAULT_CONFIG_PATH
+        if not target.exists():
+            raise FileNotFoundError(
+                f"lumilake config not found at {target}. Run "
+                f"`lumilake login <url>` to create it."
+            )
+        with open(target, "rb") as f:
+            data = tomllib.load(f)
+        return cls(base_url=data["base_url"])
+
+    def save(self, path: Path | str | None = None) -> None:
+        target = Path(path) if path else DEFAULT_CONFIG_PATH
+        target.parent.mkdir(parents=True, exist_ok=True)
+        body = f'base_url = "{self.base_url}"\n'
+        target.write_text(body, encoding="utf-8")
+        logger.info("saved lumilake config to %s", target)