pawabase 0.3.0__py3-none-any.whl

pawabase/__init__.py

@@ -0,0 +1,72 @@
+"""Pawabase for Python: the client SDK.
+
+Talk to a Pawabase environment from an app, a script or a server:
+
+    from pawabase import Pawabase
+
+    pb = Pawabase("https://api.example.com", "pb_pk_…")          # AsyncPawabase for asyncio
+    pb.auth.sign_in_with_password(email="ada@example.com", password="…")
+    posts = pb.from_("posts").eq("status", "live").order("-created_at").limit(10).execute()
+    pb.storage.from_("avatars").upload("ada.png", data)
+    pb.functions.invoke("orders.create", sku="A1")
+
+* ``pb.from_(resource)``    records: queries, create, update, delete       (:mod:`pawabase.data`)
+* ``pb.auth``               accounts, sessions, MFA, devices, API keys, organizations (:mod:`pawabase.auth`)
+* ``pb.storage``            buckets, objects, signed links, image transforms (:mod:`pawabase.storage`)
+* ``pb.functions`` / ``pb.flows`` / ``pb.routes``  call what you have defined (:mod:`pawabase.callables`)
+* ``pb.realtime``           channels, presence, live record changes        (:mod:`pawabase.realtime`)
+* ``pb.admin``              manage users with a secret key                  (:mod:`pawabase.admin`)
+* ``pb.manage``             configure the environment with a secret key     (:mod:`pawabase.manage`)
+
+Writing functions that run *on* Pawabase (and the ``pawabase`` command) is a separate package: ``pawabase-functions``.
+"""
+
+from __future__ import annotations
+
+import pkgutil
+
+# ``pawabase-functions`` installs its modules (``pawabase.functions``…) into this same package.
+__path__ = pkgutil.extend_path(__path__, __name__)
+
+from .auth import FileSessionStore, MemorySessionStore, Session, SessionStore, SignInResult  # noqa: E402
+from .client import AsyncPawabase, Pawabase  # noqa: E402
+from .data import Page, QueryError  # noqa: E402
+from .errors import (  # noqa: E402
+    AuthenticationError,
+    ConfigError,
+    ConflictError,
+    ForbiddenError,
+    NetworkError,
+    NotFoundError,
+    PawabaseError,
+    QuotaExceededError,
+    RateLimitedError,
+    RealtimeError,
+    ServerError,
+    ValidationError,
+)
+
+__version__ = "0.3.0"
+__all__ = [
+    "AsyncPawabase",
+    "AuthenticationError",
+    "ConfigError",
+    "ConflictError",
+    "FileSessionStore",
+    "ForbiddenError",
+    "MemorySessionStore",
+    "NetworkError",
+    "NotFoundError",
+    "Page",
+    "Pawabase",
+    "PawabaseError",
+    "QueryError",
+    "QuotaExceededError",
+    "RateLimitedError",
+    "RealtimeError",
+    "ServerError",
+    "Session",
+    "SessionStore",
+    "SignInResult",
+    "ValidationError",
+]

pawabase/_core.py

@@ -0,0 +1,78 @@
+"""Helpers shared by the blocking and the async client."""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable, Mapping
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from .errors import ConfigError
+
+RETRIED_STATUSES = frozenset({502, 503, 504})
+#: A 429 means the request was *not* processed, so it is safe to wait and send it again whatever the method.
+MAX_RATE_WAITS = 8
+MAX_RATE_WAIT_SECONDS = 20.0
+
+
+def rate_wait(response: httpx.Response) -> float:
+    """How long the gateway asked to wait (``Retry-After`` or the body's ``retry_after``), at least one second, at most 20."""
+    asked: Any = response.headers.get("retry-after")
+    if asked is None:
+        try:
+            asked = response.json().get("retry_after")
+        except (ValueError, AttributeError):
+            asked = None
+    try:
+        return min(max(float(asked), 1.0), MAX_RATE_WAIT_SECONDS)
+    except (TypeError, ValueError):
+        return 1.0
+
+
+def then(value: Any, function: Callable[[Any], Any]) -> Any:
+    """Apply *function* to a result that is a value (blocking client) or an awaitable (async client): the logic is written once."""
+    if inspect.isawaitable(value):
+
+        async def finish() -> Any:
+            return function(await value)
+
+        return finish()
+    return function(value)
+
+
+def chain(value: Any, function: Callable[[Any], Any]) -> Any:
+    """Like :func:`then`, for a *function* that itself returns a value or an awaitable."""
+    if inspect.isawaitable(value):
+
+        async def finish() -> Any:
+            out = function(await value)
+            return await out if inspect.isawaitable(out) else out
+
+        return finish()
+    return function(value)
+
+
+def path_of(*parts: Any) -> str:
+    """Join URL path parts, quoting each (a key may contain ``/``: it stays a path)."""
+    return "/".join(quote(str(p), safe="") for p in parts)
+
+
+def key_path(key: str) -> str:
+    """An object key as a path: segments quoted, slashes kept."""
+    return "/".join(quote(segment, safe="") for segment in key.lstrip("/").split("/"))
+
+
+def compact(values: Mapping[str, Any]) -> dict[str, Any]:
+    """*values* without the ``None``\\ s."""
+    return {k: v for k, v in values.items() if v is not None}
+
+
+def is_secret_key(key: str) -> bool:
+    return key.startswith("pb_sk_")
+
+
+def require_async(client: Any, what: str) -> None:
+    if not getattr(client, "is_async", False):
+        raise ConfigError(f"{what} needs the async client: use AsyncPawabase.")

pawabase/admin.py

@@ -0,0 +1,230 @@
+"""``pb.admin``: administer the environment's users, organizations and roles, with the environment's secret key (``pb_sk_…``).
+
+These are the people who sign in to *your* application, not the project's own team. Every call is scoped to the client's environment; a
+user of one environment is never visible in another.
+
+    pb.admin.users.create(email="ada@example.com", password="…", roles=["editor"])
+    pb.admin.users.update(user_id, disabled=True)
+    pb.admin.orgs.add_member("acme", email="ada@example.com", role="admin")
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from . import _core
+from .manage._base import Service, seg
+
+
+class _Admin(Service):
+    def path(self, suffix: str = "") -> str:
+        return f"/platform/v1/envs/{_core.path_of(self.env)}/auth{suffix}"
+
+
+class Users(_Admin):
+    def search(self, *, search: str | None = None, status: str | None = None, limit: int = 50, offset: int = 0) -> Any:
+        """``search`` matches email, username and name. ``status``: ``disabled``, ``unverified``, ``locked``, ``mfa``, ``no_mfa``."""
+        return self.get("/users", search=search, status=status, limit=limit, offset=offset)
+
+    def get_user(self, user_id: str) -> Any:
+        return self.get(seg("users", user_id))
+
+    def create(
+        self, *, email: str, password: str | None = None, username: str | None = None, name: str = "", email_verified: bool = True,
+        user_metadata: Mapping[str, Any] | None = None, app_metadata: Mapping[str, Any] | None = None, roles: Sequence[str] = (),
+    ) -> Any:
+        """Create an account without the sign-up restrictions (allow-lists, password policy aside). ``app_metadata`` is for your server only."""
+        body: dict[str, Any] = {"email": email, "name": name, "email_verified": email_verified, "roles": list(roles), "user_metadata": dict(user_metadata or {}), "app_metadata": dict(app_metadata or {})}
+        if password is not None:
+            body["password"] = password
+        if username is not None:
+            body["username"] = username
+        return self.post("/users", body)
+
+    def update(
+        self, user_id: str, *, name: str | None = None, email_verified: bool | None = None, disabled: bool | None = None, password: str | None = None,
+        user_metadata: Mapping[str, Any] | None = None, app_metadata: Mapping[str, Any] | None = None, roles: Sequence[str] | None = None,
+        unlock: bool | None = None,
+    ) -> Any:
+        """Change what is given. ``disabled=True`` blocks sign-in and ends sessions; ``unlock=True`` clears a lockout; ``roles`` replaces the user's roles."""
+        given = {"name": name, "email_verified": email_verified, "disabled": disabled, "password": password, "user_metadata": user_metadata,
+                 "app_metadata": app_metadata, "roles": None if roles is None else list(roles), "unlock": unlock}
+        return self.patch(seg("users", user_id), {k: v for k, v in given.items() if v is not None})
+
+    def delete_user(self, user_id: str) -> Any:
+        return self.delete(seg("users", user_id))
+
+    def history(self, user_id: str) -> Any:
+        """The user's recent sign-ins and security events."""
+        return self.get(seg("users", user_id, "history"))
+
+    def reset_mfa(self, user_id: str) -> Any:
+        """Remove the user's second factors, so they can sign in with a password alone and enrol again."""
+        return self.post(seg("users", user_id, "mfa", "reset"))
+
+    def grant(self, user_id: str, permissions: Sequence[str]) -> Any:
+        """Give the user permissions directly, beyond their roles' (``posts:write``, ``billing:*``)."""
+        return self.post(seg("users", user_id, "permissions"), {"permissions": list(permissions)})
+
+    def revoke(self, user_id: str, permissions: Sequence[str]) -> Any:
+        return self._c._call("DELETE", self.path(seg("users", user_id, "permissions")), json={"permissions": list(permissions)})
+
+    def revoke_sessions(self, user_id: str) -> Any:
+        """Sign the user out everywhere."""
+        return self.post(seg("users", user_id, "sessions", "revoke"))
+
+    def revoke_session(self, user_id: str, session_id: str) -> Any:
+        return self.delete(seg("users", user_id, "sessions", session_id))
+
+    def devices(self, user_id: str) -> Any:
+        return self.get(seg("users", user_id, "devices"))
+
+    def forget_device(self, user_id: str, device_id: str) -> Any:
+        return self.delete(seg("users", user_id, "devices", device_id))
+
+    def api_keys(self, user_id: str) -> Any:
+        """The user's own API keys (never the secrets)."""
+        return self.get(seg("users", user_id, "api-keys"))
+
+
+class Roles(_Admin):
+    def list(self) -> Any:
+        """Roles with their permissions."""
+        return self.get("/roles")
+
+    def put(self, name: str, permissions: Sequence[str], *, description: str = "") -> Any:  # type: ignore[override]
+        """Create or replace a role. Names are lowercase (``editor``, ``org:billing``); permissions are ``resource:action`` patterns with ``*`` wildcards."""
+        return Service.put(self, "/roles", {"name": name, "description": description, "permissions": list(permissions)})
+
+    def remove(self, name: str) -> Any:
+        return self.delete(seg("roles", name))
+
+
+class Orgs(_Admin):
+    """Organizations (tenants) and their members. A member's role is ``owner``, ``admin`` or ``member``."""
+
+    def list(self) -> Any:
+        return self.get("/orgs")
+
+    def get_org(self, slug: str) -> Any:
+        return self.get(seg("orgs", slug))
+
+    def create(self, slug: str, name: str, *, owner_email: str | None = None, metadata: Mapping[str, Any] | None = None) -> Any:
+        body: dict[str, Any] = {"slug": slug, "name": name, "metadata": dict(metadata or {})}
+        if owner_email:
+            body["owner_email"] = owner_email
+        return self.post("/orgs", body)
+
+    def update(self, slug: str, *, name: str | None = None, metadata: Mapping[str, Any] | None = None) -> Any:
+        return self.patch(seg("orgs", slug), {k: v for k, v in {"name": name, "metadata": metadata}.items() if v is not None})
+
+    def remove(self, slug: str) -> Any:
+        return self.delete(seg("orgs", slug))
+
+    def add_member(self, slug: str, *, email: str, role: str = "member") -> Any:
+        """Add an existing user straight in."""
+        return self.post(seg("orgs", slug, "members"), {"email": email, "role": role})
+
+    def set_member_role(self, slug: str, user_id: str, role: str) -> Any:
+        return self.patch(seg("orgs", slug, "members", user_id), {"role": role})
+
+    def remove_member(self, slug: str, user_id: str) -> Any:
+        return self.delete(seg("orgs", slug, "members", user_id))
+
+    def invite(self, slug: str, *, email: str, role: str = "member", redirect_to: str | None = None) -> Any:
+        """Mail an invitation; ``redirect_to`` must be one of the environment's allowed redirect URLs."""
+        return self.post(seg("orgs", slug, "invitations"), {"email": email, "role": role, **({"redirect_to": redirect_to} if redirect_to else {})})
+
+
+class Invitations(_Admin):
+    def list(self) -> Any:
+        """Pending and past invitations across organizations."""
+        return self.get("/invitations")
+
+    def resend(self, invitation_id: str, *, redirect_to: str | None = None) -> Any:
+        return self.post(seg("invitations", invitation_id, "resend"), {"redirect_to": redirect_to} if redirect_to else {})
+
+    def revoke(self, invitation_id: str) -> Any:
+        return self.delete(seg("invitations", invitation_id))
+
+
+class Sessions(_Admin):
+    def list(self, *, limit: int | None = None) -> Any:
+        """Active sessions across users."""
+        return self.get("/sessions", limit=limit)
+
+    def revoke(self, family: str) -> Any:
+        """End one session (all its refresh tokens)."""
+        return self.delete(seg("sessions", family))
+
+
+class ApiKeys(_Admin):
+    """API keys users made for themselves."""
+
+    def list(self, *, limit: int | None = None) -> Any:
+        return self.get("/api-keys", limit=limit)
+
+    def revoke(self, key_id: str) -> Any:
+        return self.delete(seg("api-keys", key_id))
+
+
+class Devices(_Admin):
+    def list(self, *, limit: int | None = None) -> Any:
+        """Recent devices people signed in from."""
+        return self.get("/devices", limit=limit)
+
+
+class Insight(_Admin):
+    """Events, statistics, backup and the hosted pages."""
+
+    def events(self, *, kind: str | None = None, failed: bool = False, limit: int = 100) -> Any:
+        """Authentication events (sign-ins, sign-ups, resets, MFA…). ``failed=True`` for failures only."""
+        return self.get("/events", kind=kind, failed="true" if failed else None, limit=limit)
+
+    def stats(self) -> Any:
+        """Counts of users, sign-ins, MFA use and failures."""
+        return self.get("/stats")
+
+    def backup(self) -> Any:
+        """Every identity (users, organizations, roles, factors) as a document."""
+        return self.get("/backup")
+
+    def restore(self, identities: Mapping[str, Any], *, replace: bool = False, dry_run: bool = False) -> Any:
+        """Apply the ``identities`` of a backup. ``dry_run=True`` reports what would change."""
+        return self.post("/restore", {"identities": dict(identities), "replace": replace, "dry_run": dry_run})
+
+    def preview_token_profile(self, profile: Mapping[str, Any], user_id: str, *, org: str | None = None) -> Any:
+        """The claims a token profile would put in a token for this user (and organization), without issuing one."""
+        body = {"profile": dict(profile), "user_id": user_id, **({"org": org} if org else {})}
+        return self.post("/token-profiles/preview", body)
+
+    def hosted_source(self, page: str, *, branding: Mapping[str, Any] | None = None, form: Mapping[str, Any] | None = None) -> Any:
+        """The HTML a hosted sign-in page is served as for the branding being edited (the saved branding when omitted)."""
+        return self.post("/hosted-source", {"page": page, **({"branding": dict(branding)} if branding is not None else {}), **({"form": dict(form)} if form is not None else {})})
+
+
+class Admin:
+    users: Users
+    roles: Roles
+    orgs: Orgs
+    invitations: Invitations
+    sessions: Sessions
+    api_keys: ApiKeys
+    devices: Devices
+    insight: Insight
+
+    def __init__(self, client: Any, environment: str | None = None) -> None:
+        self._client = client
+        self._environment = environment
+        self.users = Users(client, environment)
+        self.roles = Roles(client, environment)
+        self.orgs = Orgs(client, environment)
+        self.invitations = Invitations(client, environment)
+        self.sessions = Sessions(client, environment)
+        self.api_keys = ApiKeys(client, environment)
+        self.devices = Devices(client, environment)
+        self.insight = Insight(client, environment)
+
+    def environment(self, name: str) -> Admin:
+        return Admin(self._client, name)