supython 0.1.0__py3-none-any.whl

supython/client/__init__.py

@@ -0,0 +1,67 @@
+from ._auth import (
+    SIGNED_IN,
+    SIGNED_OUT,
+    TOKEN_REFRESHED,
+    USER_UPDATED,
+    AuthChangeCallback,
+    AuthError,
+    Session,
+    SupythonResponse,
+    TokenResponse,
+    UserResponse,
+)
+from ._client import Client
+from ._config import (
+    AuthOptions,
+    AuthStorageBackend,
+    ClientOptions,
+    FileAuthStorage,
+    MemoryAuthStorage,
+)
+from ._functions import FunctionsClient, FunctionsError
+from ._storage import (
+    BucketResponse,
+    ObjectResponse,
+    SignedUrlResponse,
+    StorageBucket,
+    StorageClient,
+    StorageError,
+)
+
+
+def create_client(
+    supython_url: str,
+    anon_key: str = "",
+    *,
+    options: ClientOptions | None = None,
+) -> Client:
+    return Client(supython_url, anon_key, options=options)
+
+
+__all__ = [
+    "create_client",
+    "Client",
+    "ClientOptions",
+    "AuthOptions",
+    "AuthError",
+    "AuthChangeCallback",
+    "Session",
+    "SupythonResponse",
+    "TokenResponse",
+    "UserResponse",
+    "SIGNED_IN",
+    "SIGNED_OUT",
+    "TOKEN_REFRESHED",
+    "USER_UPDATED",
+    "StorageClient",
+    "StorageBucket",
+    "StorageError",
+    "BucketResponse",
+    "ObjectResponse",
+    "SignedUrlResponse",
+    "FunctionsClient",
+    "FunctionsError",
+    "AuthStorageBackend",
+    "MemoryAuthStorage",
+    "FileAuthStorage",
+]

supython/client/_auth.py

@@ -0,0 +1,249 @@
+from __future__ import annotations
+
+import contextlib
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, Generic, TypeVar
+
+import httpx
+
+from ._config import _parse_error_detail
+
+T = TypeVar("T")
+
+
+@dataclass
+class AuthError:
+    code: str
+    message: str
+    status: int
+
+
+@dataclass
+class UserResponse:
+    id: str
+    email: str
+    created_at: str
+
+
+@dataclass
+class TokenResponse:
+    access_token: str
+    token_type: str
+    expires_in: int
+    refresh_token: str
+    user: UserResponse
+
+
+@dataclass
+class Session:
+    access_token: str
+    refresh_token: str
+    expires_in: int
+    user: UserResponse | None
+
+
+@dataclass
+class SupythonResponse(Generic[T]):
+    data: T | None = None
+    error: AuthError | None = None
+
+
+SIGNED_IN = "SIGNED_IN"
+SIGNED_OUT = "SIGNED_OUT"
+TOKEN_REFRESHED = "TOKEN_REFRESHED"
+USER_UPDATED = "USER_UPDATED"
+
+
+AuthChangeCallback = Callable[[str, Session | None], None]
+
+
+def _parse_token_response(body: dict[str, Any]) -> TokenResponse:
+    user_body = body["user"]
+    user = UserResponse(
+        id=str(user_body["id"]),
+        email=user_body["email"],
+        created_at=user_body["created_at"],
+    )
+    return TokenResponse(
+        access_token=body["access_token"],
+        token_type=body.get("token_type", "bearer"),
+        expires_in=body["expires_in"],
+        refresh_token=body["refresh_token"],
+        user=user,
+    )
+
+
+def _parse_user_response(body: dict[str, Any]) -> UserResponse:
+    return UserResponse(
+        id=str(body["id"]),
+        email=body["email"],
+        created_at=body["created_at"],
+    )
+
+
+def _make_auth_error(resp: httpx.Response) -> AuthError:
+    try:
+        body = resp.json()
+    except Exception:
+        return AuthError("network_error", resp.text or f"HTTP {resp.status_code}", resp.status_code)
+    code, message = _parse_error_detail(body)
+    return AuthError(code, message, resp.status_code)
+
+
+class AuthClient:
+    def __init__(self, client: Any, base_url: str) -> None:
+        self._client = client
+        self._url = base_url
+        self._http = httpx.AsyncClient()
+        self._callbacks: list[AuthChangeCallback] = []
+
+    def on_auth_state_change(self, callback: AuthChangeCallback) -> Callable[[], None]:
+        self._callbacks.append(callback)
+
+        def unsubscribe() -> None:
+            with contextlib.suppress(ValueError):
+                self._callbacks.remove(callback)
+
+        return unsubscribe
+
+    def _emit(self, event: str, session: Session | None) -> None:
+        for cb in self._callbacks:
+            with contextlib.suppress(Exception):
+                cb(event, session)
+
+    async def sign_up(self, email: str, password: str) -> SupythonResponse[TokenResponse]:
+        try:
+            resp = await self._http.post(
+                f"{self._url}/signup",
+                json={"email": email, "password": password},
+            )
+        except httpx.HTTPError as exc:
+            return SupythonResponse(error=AuthError("network_error", str(exc), 0))
+
+        if resp.status_code >= 400:
+            return SupythonResponse(error=_make_auth_error(resp))
+
+        token_resp = _parse_token_response(resp.json())
+        session = await self._save_session(token_resp)
+        self._emit(SIGNED_IN, session)
+        return SupythonResponse(data=token_resp)
+
+    async def sign_in_with_password(
+        self, email: str, password: str
+    ) -> SupythonResponse[TokenResponse]:
+        try:
+            resp = await self._http.post(
+                f"{self._url}/token",
+                json={"email": email, "password": password},
+            )
+        except httpx.HTTPError as exc:
+            return SupythonResponse(error=AuthError("network_error", str(exc), 0))
+
+        if resp.status_code >= 400:
+            return SupythonResponse(error=_make_auth_error(resp))
+
+        token_resp = _parse_token_response(resp.json())
+        session = await self._save_session(token_resp)
+        self._emit(SIGNED_IN, session)
+        return SupythonResponse(data=token_resp)
+
+    async def sign_out(self) -> SupythonResponse[None]:
+        refresh_token = self._client._refresh_token
+        if not refresh_token:
+            return SupythonResponse(data=None)
+
+        try:
+            resp = await self._http.post(
+                f"{self._url}/logout",
+                json={"refresh_token": refresh_token},
+            )
+        except httpx.HTTPError as exc:
+            return SupythonResponse(error=AuthError("network_error", str(exc), 0))
+
+        await self._clear_session()
+        self._emit(SIGNED_OUT, None)
+
+        if resp.status_code >= 400:
+            return SupythonResponse(error=_make_auth_error(resp))
+
+        return SupythonResponse(data=None)
+
+    async def refresh_session(self) -> SupythonResponse[TokenResponse]:
+        refresh_token = self._client._refresh_token
+        if not refresh_token:
+            err = AuthError("no_session", "No refresh token available", 401)
+            await self._clear_session()
+            self._emit(SIGNED_OUT, None)
+            return SupythonResponse(error=err)
+
+        try:
+            resp = await self._http.post(
+                f"{self._url}/refresh",
+                json={"refresh_token": refresh_token},
+            )
+        except httpx.HTTPError as exc:
+            return SupythonResponse(error=AuthError("network_error", str(exc), 0))
+
+        if resp.status_code >= 400:
+            await self._clear_session()
+            self._emit(SIGNED_OUT, None)
+            return SupythonResponse(error=_make_auth_error(resp))
+
+        token_resp = _parse_token_response(resp.json())
+        session = await self._save_session(token_resp)
+        self._emit(TOKEN_REFRESHED, session)
+        return SupythonResponse(data=token_resp)
+
+    async def get_user(self) -> SupythonResponse[UserResponse]:
+        access_token = self._client._access_token
+        if not access_token:
+            return SupythonResponse(error=AuthError("no_session", "Not authenticated", 401))
+
+        try:
+            resp = await self._http.get(
+                f"{self._url}/user",
+                headers={"Authorization": f"Bearer {access_token}"},
+            )
+        except httpx.HTTPError as exc:
+            return SupythonResponse(error=AuthError("network_error", str(exc), 0))
+
+        if resp.status_code >= 400:
+            return SupythonResponse(error=_make_auth_error(resp))
+
+        user = _parse_user_response(resp.json())
+        previous = self._client._user
+        self._client._user = user
+        if previous is not None and previous != user:
+            self._emit(USER_UPDATED, self.get_session())
+        return SupythonResponse(data=user)
+
+    def get_session(self) -> Session | None:
+        access_token = self._client._access_token
+        refresh_token = self._client._refresh_token
+        if not access_token:
+            return None
+        return Session(
+            access_token=access_token,
+            refresh_token=refresh_token or "",
+            expires_in=0,
+            user=self._client._user,
+        )
+
+    async def _save_session(self, token_resp: TokenResponse) -> Session:
+        self._client.set_session(
+            token_resp.access_token,
+            token_resp.refresh_token,
+            user=token_resp.user,
+        )
+        await self._client._persist_session()
+        return Session(
+            access_token=token_resp.access_token,
+            refresh_token=token_resp.refresh_token,
+            expires_in=token_resp.expires_in,
+            user=token_resp.user,
+        )
+
+    async def _clear_session(self) -> None:
+        self._client.clear_session()
+        await self._client._persist_session()

supython/client/_client.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ._auth import SIGNED_IN, AuthClient, UserResponse
+from ._config import (
+    ClientOptions,
+    MemoryAuthStorage,
+    _build_auth_url,
+    _build_functions_url,
+    _build_rest_url,
+    _build_storage_url,
+    _build_ws_url,
+)
+from ._functions import FunctionsClient
+from ._storage import StorageClient
+
+
+class Client:
+    def __init__(
+        self,
+        supython_url: str,
+        anon_key: str = "",
+        *,
+        options: ClientOptions | None = None,
+    ) -> None:
+        self.base_url = supython_url.rstrip("/")
+        self._anon_key = anon_key
+        self._opts = options or ClientOptions()
+        self._access_token: str | None = None
+        self._refresh_token: str | None = None
+        self._user: UserResponse | None = None
+
+        if self._opts.auth.storage is None:
+            self._storage_backend = MemoryAuthStorage()
+        else:
+            self._storage_backend = self._opts.auth.storage
+
+        self.auth = AuthClient(self, _build_auth_url(self.base_url))
+        self.storage = StorageClient(_build_storage_url(self.base_url), self._anon_key, self)
+        self.functions = FunctionsClient(
+            _build_functions_url(self.base_url), self._anon_key, self
+        )
+
+        self._rest_url = _build_rest_url(self.base_url)
+        self._ws_url = _build_ws_url(self.base_url)
+
+    def set_session(
+        self,
+        access_token: str,
+        refresh_token: str,
+        *,
+        user: UserResponse | None = None,
+    ) -> None:
+        self._access_token = access_token
+        self._refresh_token = refresh_token
+        if user is not None:
+            self._user = user
+
+    def clear_session(self) -> None:
+        self._access_token = None
+        self._refresh_token = None
+        self._user = None
+
+    async def _persist_session(self) -> None:
+        if not self._opts.auth.persist_session:
+            return
+        # Persistence is best-effort: the in-memory session is the source of
+        # truth and a failed write should not break the auth response contract.
+        try:
+            if self._access_token and self._refresh_token:
+                await self._storage_backend.save(
+                    {
+                        "access_token": self._access_token,
+                        "refresh_token": self._refresh_token,
+                    }
+                )
+            else:
+                await self._storage_backend.clear()
+        except Exception:
+            pass
+
+    async def restore_session(self) -> bool:
+        try:
+            data = await self._storage_backend.load()
+        except Exception:
+            return False
+        if not data:
+            return False
+        access_token = data.get("access_token")
+        refresh_token = data.get("refresh_token")
+        if not access_token:
+            return False
+        self.set_session(access_token, refresh_token or "")
+        self.auth._emit(SIGNED_IN, self.auth.get_session())
+        return True
+
+    def _auth_headers(self) -> dict[str, str]:
+        headers: dict[str, str] = {}
+        if self._anon_key:
+            headers["apikey"] = self._anon_key
+        if self._access_token:
+            headers["Authorization"] = f"Bearer {self._access_token}"
+        return headers
+
+    def from_(self, table: str) -> Any:
+        try:
+            from postgrest import PostgrestClient
+        except ImportError as exc:
+            raise ImportError(
+                "PostgREST query builder requires postgrest-py. "
+                "Install with: pip install supython[client]"
+            ) from exc
+        return PostgrestClient(
+            self._rest_url, headers=self._auth_headers()
+        ).from_(table)
+
+    def rpc(self, fn_name: str, params: dict | None = None) -> Any:
+        try:
+            from postgrest import PostgrestClient
+        except ImportError as exc:
+            raise ImportError(
+                "PostgREST query builder requires postgrest-py. "
+                "Install with: pip install supython[client]"
+            ) from exc
+        return PostgrestClient(
+            self._rest_url, headers=self._auth_headers()
+        ).rpc(fn_name, params or {})
+
+    def channel(self, topic: str) -> Any:
+        try:
+            from realtime import RealtimeClient
+        except ImportError as exc:
+            raise ImportError(
+                "Realtime client requires the realtime package. "
+                "Install with: pip install supython[client]"
+            ) from exc
+        client = RealtimeClient(self._ws_url, params={"apikey": self._anon_key})
+        return client.channel(topic)
+
+    async def _auto_refresh(self) -> bool:
+        if not self._opts.auth.auto_refresh_token:
+            return False
+        result = await self.auth.refresh_session()
+        return result.error is None

supython/client/_config.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    pass
+
+
+@runtime_checkable
+class AuthStorageBackend(Protocol):
+    async def load(self) -> dict[str, str] | None: ...
+    async def save(self, data: dict[str, str]) -> None: ...
+    async def clear(self) -> None: ...
+
+
+class MemoryAuthStorage:
+    def __init__(self) -> None:
+        self._data: dict[str, str] | None = None
+
+    async def load(self) -> dict[str, str] | None:
+        return self._data
+
+    async def save(self, data: dict[str, str]) -> None:
+        self._data = dict(data)
+
+    async def clear(self) -> None:
+        self._data = None
+
+
+class FileAuthStorage:
+    def __init__(self, path: Path) -> None:
+        self._path = path
+
+    async def load(self) -> dict[str, str] | None:
+        if not self._path.exists():
+            return None
+        text = self._path.read_text(encoding="utf-8").strip()
+        if not text:
+            return None
+        return json.loads(text)
+
+    async def save(self, data: dict[str, str]) -> None:
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        self._path.write_text(json.dumps(data), encoding="utf-8")
+
+    async def clear(self) -> None:
+        if self._path.exists():
+            self._path.write_text("", encoding="utf-8")
+
+
+@dataclass
+class AuthOptions:
+    storage: AuthStorageBackend | None = None
+    auto_refresh_token: bool = True
+    persist_session: bool = True
+
+
+@dataclass
+class ClientOptions:
+    auth: AuthOptions = field(default_factory=AuthOptions)
+
+
+def _build_rest_url(base_url: str) -> str:
+    return f"{base_url}/rest/v1"
+
+
+def _build_auth_url(base_url: str) -> str:
+    return f"{base_url}/auth/v1"
+
+
+def _build_storage_url(base_url: str) -> str:
+    return f"{base_url}/storage/v1"
+
+
+def _build_functions_url(base_url: str) -> str:
+    return f"{base_url}/functions"
+
+
+def _build_ws_url(base_url: str) -> str:
+    return base_url.replace("http://", "ws://").replace("https://", "wss://") + "/realtime/v1"
+
+
+def _parse_error_detail(body: Any) -> tuple[str, str]:
+    if isinstance(body, dict):
+        detail = body.get("detail", body)
+        if isinstance(detail, dict):
+            return detail.get("code", "unknown"), detail.get("message", str(body))
+        return "unknown", str(detail)
+    return "unknown", str(body)

supython/client/_functions.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from ._auth import SupythonResponse
+from ._config import _parse_error_detail
+
+
+@dataclass
+class FunctionsError:
+    code: str
+    message: str
+    status: int
+
+
+def _make_functions_error(resp: httpx.Response) -> FunctionsError:
+    try:
+        body = resp.json()
+    except Exception:
+        return FunctionsError(
+            "network_error", resp.text or f"HTTP {resp.status_code}", resp.status_code
+        )
+    code, message = _parse_error_detail(body)
+    return FunctionsError(code, message, resp.status_code)
+
+
+class FunctionsClient:
+    def __init__(self, base_url: str, anon_key: str, client: Any) -> None:
+        self._url = base_url
+        self._anon_key = anon_key
+        self._client = client
+        self._http = httpx.AsyncClient()
+
+    def _headers(self) -> dict[str, str]:
+        headers: dict[str, str] = {"Content-Type": "application/json"}
+        if self._anon_key:
+            headers["apikey"] = self._anon_key
+        access_token = self._client._access_token
+        if access_token:
+            headers["Authorization"] = f"Bearer {access_token}"
+        return headers
+
+    async def invoke(
+        self,
+        name: str,
+        *,
+        body: dict[str, Any] | None = None,
+        method: str = "POST",
+    ) -> SupythonResponse[Any]:
+        url = f"{self._url}/{name}"
+        try:
+            resp = await self._http.request(
+                method, url, json=body, headers=self._headers()
+            )
+        except httpx.HTTPError as exc:
+            return SupythonResponse(error=FunctionsError("network_error", str(exc), 0))
+
+        if resp.status_code >= 400:
+            return SupythonResponse(error=_make_functions_error(resp))
+
+        try:
+            data = resp.json()
+        except Exception:
+            data = resp.text
+
+        return SupythonResponse(data=data)