jotabase 0.7.0__py3-none-any.whl

jotabase/__init__.py

@@ -0,0 +1,12 @@
+"""Python client for jotaBase.
+
+Planned in docs/PYTHON-CLIENT.md.
+"""
+
+# Set by scripts/set-version.mjs together with the npm packages. Never edit by hand.
+__version__ = "0.7.0"
+
+from .client import DEFAULT_URL, Database, connect  # noqa: E402
+from .errors import AuthError, JotabaseError  # noqa: E402
+
+__all__ = ["__version__", "connect", "Database", "DEFAULT_URL", "JotabaseError", "AuthError"]

jotabase/client.py

@@ -0,0 +1,362 @@
+"""Connecting to one database, and signing in to it.
+
+Three ways in, the same as the server's data plane (CLAUDE.md, "Control plane vs
+data plane"; docs/PYTHON-CLIENT.md, "What it does" 1):
+
+- a **secret key** (``sk_``): servers and scripts, bypasses access rules;
+- a **publishable key** (``pk_``), optionally with an app user signed in through
+  ``sign_in``: subject to access rules;
+- **no key**: a public ``@handle/name`` database, read-only.
+
+The credential sent is the app user's token if one is signed in, else the key,
+else nothing -- and with nothing, **no Authorization header at all**, never
+``Bearer None``, which the server would refuse as a bad credential instead of
+reading as an anonymous request. That is the JS client's ``credential()`` rule.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from typing import Any
+
+import httpx
+
+from . import __version__
+from .errors import AuthError, JotabaseError
+
+DEFAULT_URL = "https://api.jotabase.com"
+DEFAULT_TIMEOUT = 30.0
+
+# "Use the database's current credential" -- distinct from None, which sends none.
+_CURRENT = object()
+
+
+class Database:
+    """One jotaBase database. Create it with :func:`jotabase.connect`."""
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        key: str | None = None,
+        token: str | None = None,
+        url: str = DEFAULT_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        transport: httpx.BaseTransport | None = None,
+    ):
+        name = name.strip().strip("/")
+        if not name:
+            raise ValueError("a database name is required")
+        if name.startswith("@") and name.count("/") != 1:
+            raise ValueError("a public database is addressed as '@handle/name'")
+        if not name.startswith("@") and "/" in name:
+            raise ValueError(
+                f"{name!r} is not a database name; a public one is written '@handle/name'"
+            )
+        self.name = name
+        self.url = url.rstrip("/")
+        self.key = key
+        self.token = token
+        self.user: dict[str, Any] | None = None
+        # Seqs of this Database's own writes, so a listener can leave them out.
+        self._own_seqs: set[int] = set()
+        self._own_order: deque[int] = deque()
+        self._listeners: list[Any] = []
+        self._http = httpx.Client(
+            base_url=self.url,
+            timeout=timeout,
+            transport=transport,
+            headers={"User-Agent": f"jotabase-python/{__version__}"},
+        )
+
+    # -- lifecycle -----------------------------------------------------------
+
+    def close(self) -> None:
+        for listener in list(self._listeners):
+            listener.stop()
+        for engine in self.__dict__.get("_sql", {}).values():
+            engine.close()
+        self._http.close()
+
+    def __enter__(self) -> "Database":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"<jotabase.Database {self.name!r} at {self.url} ({self.credential_kind})>"
+
+    # -- credentials ---------------------------------------------------------
+
+    @property
+    def is_public(self) -> bool:
+        """Addressed as ``@handle/name``: someone's published database."""
+        return self.name.startswith("@")
+
+    @property
+    def credential(self) -> str | None:
+        """What is sent as ``Authorization: Bearer``: token, else key, else nothing."""
+        return self.token or self.key or None
+
+    @property
+    def credential_kind(self) -> str:
+        """``app_user``, ``secret``, ``publishable`` or ``anonymous``, from what is held.
+
+        A local reading of the credential's shape; the server decides what it
+        really is. Useful for messages, not for access decisions.
+        """
+        if self.token:
+            return "app_user"
+        if self.key and self.key.startswith("sk_"):
+            return "secret"
+        if self.key and self.key.startswith("pk_"):
+            return "publishable"
+        if self.key:
+            return "unknown"
+        return "anonymous"
+
+    # -- app users (/_auth/*) ------------------------------------------------
+
+    def sign_up(self, email: str, password: str) -> dict[str, Any]:
+        """Create an app user (role ``member``) and, when a token comes back, sign in.
+
+        A database with confirmed email required returns
+        ``verification_required: True`` and no token: the user must open the
+        emailed link, then ``sign_in``.
+        """
+        body = self._auth_post("/_auth/signup", email, password)
+        self._take_session(body)
+        return body
+
+    def sign_in(self, email: str, password: str) -> dict[str, Any]:
+        """Sign an app user in; later requests carry their token and their roles.
+
+        Raises :class:`AuthError` -- ``code='email_not_verified'`` (403) when the
+        database requires a confirmed address and this one is not.
+        """
+        body = self._auth_post("/_auth/login", email, password)
+        self._take_session(body)
+        return body
+
+    def sign_out(self) -> None:
+        """Forget the app user's token; requests go back to using the key."""
+        self.token = None
+        self.user = None
+
+    def me(self) -> dict[str, Any]:
+        """The signed-in app user's id, email, roles and whether they are verified."""
+        if not self.token:
+            raise AuthError("no app user is signed in", status=None)
+        try:
+            return self._request("GET", "/_auth/me").json()
+        except JotabaseError as e:
+            raise AuthError(str(e), e.status, e.code) from None
+
+    def _auth_post(self, path: str, email: str, password: str) -> dict[str, Any]:
+        if not self.key:
+            raise AuthError("signing app users in needs the database's publishable key")
+        # The key, never a previous user's token: /_auth answers for the database.
+        try:
+            res = self._request(
+                "POST", path, json={"email": email, "password": password}, credential=self.key
+            )
+        except JotabaseError as e:
+            raise AuthError(str(e), e.status, e.code) from None
+        return res.json()
+
+    def _take_session(self, body: dict[str, Any]) -> None:
+        if body.get("token"):
+            self.token = body["token"]
+            self.user = body.get("user")
+
+    # -- reading -------------------------------------------------------------
+
+    def fetch_changes(self, since: int = 0, on_progress=None):
+        """Everything past ``since`` as documents, in apply order; stores nothing.
+
+        Returns :class:`jotabase.sync.Changes`: ``.items``, ``.checkpoint`` (pass
+        it as ``since`` next time) and ``.latest()`` (newest version per id,
+        deleted ones left out). The bring-your-own-store path, like the JS
+        client's ``fetchChanges``.
+        """
+        from .sync import fetch_changes
+
+        return fetch_changes(self, since, on_progress)
+
+    def list_changes(self, since: int = 0, files_since: int | None = None):
+        """One ``/_sync`` without fetching any file: segments, tail and stats."""
+        from .sync import list_changes
+
+        return list_changes(self, since, files_since)
+
+    def local(self, folder=None):
+        """The local copy on disk (default ``./.jotabase/<db>/``); see :class:`LocalStore`."""
+        from .local import LocalStore
+
+        if folder is None and getattr(self, "_local", None) is not None:
+            return self._local
+        store = LocalStore(self, folder)
+        if folder is None:
+            self._local = store
+        return store
+
+    def pull(self, folder=None, on_progress=None):
+        """Bring the local copy up to date; only what changed is downloaded."""
+        return self.local(folder).pull(on_progress)
+
+    def sql_engine(self, folder=None):
+        """The DuckDB engine over the local copy; see :class:`jotabase.sql.LocalSql`."""
+        from .sql import LocalSql
+
+        store = self.local(folder)
+        engines = self.__dict__.setdefault("_sql", {})
+        key = str(store.folder.resolve())
+        if key not in engines:
+            engines[key] = LocalSql(store)
+        return engines[key]
+
+    def sql(self, query: str, params=None, folder=None):
+        """SQL over the local copy: one view per collection. Call :meth:`pull` first.
+
+        >>> db.pull()
+        >>> db.sql("SELECT status, count(*) FROM tasks GROUP BY status").df()
+        """
+        return self.sql_engine(folder).sql(query, params)
+
+    # -- live changes --------------------------------------------------------
+
+    def on_change(self, handler=None, *, since=None, pull=False, include_own=False, on_error=None):
+        """Call ``handler(change)`` for every change, from a background thread.
+
+        ``change.docs`` are the new versions (tombstones included, ``deleted``
+        set), ``change.last_seq`` the server's seq. Starts from now, or from
+        ``since``. ``pull=True`` also brings the local copy (and ``db.sql``) up to
+        date before each call. Usable as a decorator::
+
+            @db.on_change
+            def changed(change):
+                for doc in change.docs: ...
+
+        Returns a :class:`jotabase.live.Listener`; ``.stop()`` ends it, and so
+        does ``db.close()``. Needs the ``websockets`` package.
+        """
+        from .live import Listener
+
+        def start(h):
+            listener = Listener(self, h, since=since, pull=pull, include_own=include_own,
+                                on_error=on_error)
+            self._listeners.append(listener)
+            return listener
+
+        return start if handler is None else start(handler)
+
+    def _note_own_writes(self, seqs) -> None:
+        for s in seqs:
+            if s and s not in self._own_seqs:
+                self._own_seqs.add(s)
+                self._own_order.append(s)
+        while len(self._own_order) > 100_000:
+            self._own_seqs.discard(self._own_order.popleft())
+
+    # -- writing -------------------------------------------------------------
+
+    def put(self, collection: str | None, data: dict[str, Any], id: str | None = None):
+        """Create or replace one document; returns its :class:`WriteResult`.
+
+        The id is ``id``, else ``data["id"]``, else a new UUID. A document an
+        access rule refuses comes back with ``ok=False`` and the reason in
+        ``error`` -- check it; it is not raised.
+        """
+        from .push import make_doc, push
+
+        return push(self, [make_doc(collection, data, id)])[0]
+
+    def put_many(
+        self,
+        collection: str | None,
+        docs,
+        silent: bool = False,
+        on_progress=None,
+    ):
+        """Create or replace many documents, in as few requests as fit under 1 MB.
+
+        Returns :class:`WriteResults` (a list, in input order) with ``.ok`` and
+        ``.failed``. ``silent=True`` writes without notifying live listeners per
+        batch -- for bulk loads.
+        """
+        from .push import make_doc, push_many
+
+        return push_many(
+            self, (make_doc(collection, d) for d in docs), silent=silent, on_progress=on_progress
+        )
+
+    def delete(self, collection: str | None, id: str):
+        """Delete one document (a tombstone); returns its :class:`WriteResult`."""
+        from .push import make_doc, push
+
+        return push(self, [make_doc(collection, {}, id, deleted=True)])[0]
+
+    def push(self, docs: list[dict[str, Any]], silent: bool = False):
+        """Raw ``/_push`` of ready-made entries ``{id, data, deleted?, collection?}``, batched."""
+        from .push import push_many
+
+        return push_many(self, docs, silent=silent)
+
+    # -- transport -----------------------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        credential: Any = _CURRENT,
+        **kwargs: Any,
+    ) -> httpx.Response:
+        """One data-plane request to ``/{db}{path}``; raises on anything but 2xx."""
+        cred = self.credential if credential is _CURRENT else credential
+        headers = dict(kwargs.pop("headers", None) or {})
+        if cred:
+            headers["Authorization"] = f"Bearer {cred}"
+        target = path if path.startswith("/" + self.name + "/") else f"/{self.name}{path}"
+        try:
+            res = self._http.request(method, target, headers=headers, **kwargs)
+        except httpx.HTTPError as e:
+            raise JotabaseError(f"{method} {target} failed: {e}") from e
+        if res.is_success:
+            return res
+        raise _error_from(res)
+
+
+def _error_from(res: httpx.Response) -> JotabaseError:
+    try:
+        data = res.json()
+    except ValueError:
+        data = {}
+    if not isinstance(data, dict):
+        data = {}
+    message = data.get("reason") or data.get("message") or data.get("error") or res.reason_phrase
+    code = data.get("error") if isinstance(data.get("error"), str) else None
+    return JotabaseError(f"{res.status_code}: {message}", res.status_code, code)
+
+
+def connect(
+    name: str,
+    *,
+    key: str | None = None,
+    token: str | None = None,
+    url: str = DEFAULT_URL,
+    timeout: float = DEFAULT_TIMEOUT,
+    transport: httpx.BaseTransport | None = None,
+) -> Database:
+    """Open one database.
+
+    >>> db = jotabase.connect("my-app", key="sk_live_...")       # a server or script
+    >>> db = jotabase.connect("my-app", key="pk_live_...")       # an app, rules apply
+    >>> db = jotabase.connect("@jotabase/trips")                 # a public database
+
+    Nothing is sent until the first call that needs the server. ``url`` points at
+    another server (``http://localhost:8787`` for ``wrangler dev``); ``transport``
+    is for tests.
+    """
+    return Database(name, key=key, token=token, url=url, timeout=timeout, transport=transport)

jotabase/errors.py

@@ -0,0 +1,22 @@
+"""Errors raised by the client."""
+
+from __future__ import annotations
+
+
+class JotabaseError(Exception):
+    """A request the server refused, or one that never reached it.
+
+    ``status`` is the HTTP status (``None`` when no response arrived), so a caller
+    can tell an expired or wrong credential (401/403) from a transient failure --
+    the same distinction the JS client's ``SyncError`` carries. ``code`` is the
+    server's ``error`` field when it sent one (``'email_not_verified'``, ...).
+    """
+
+    def __init__(self, message: str, status: int | None = None, code: str | None = None):
+        super().__init__(message)
+        self.status = status
+        self.code = code
+
+
+class AuthError(JotabaseError):
+    """Sign-up, sign-in or identity failed (``/_auth/*``)."""

jotabase/live.py

@@ -0,0 +1,244 @@
+"""Live changes over ``/_ws``.
+
+docs/PYTHON-CLIENT.md, "What it does" 6. What the server sends, and what this
+does with it:
+
+- ``{type: 'change', last_seq}`` (strategies ``live`` and ``batch``) means
+  "there is something to read" -- sent **after** the publish lands. The
+  listener reads it with ``fetch_changes(since=checkpoint)`` and hands the new
+  documents to the handler.
+- ``{type: 'change', last_seq, docs}`` (strategy ``push``) carries the documents
+  themselves, already filtered for this socket's roles, so nothing is read.
+- ``{type: 'log', ...}`` frames are the dashboard's server log; ignored.
+
+On every (re)connect the listener first catches up from its checkpoint, so a
+dropped connection loses nothing. The credential goes in the
+``Authorization`` header, never in the URL (decision 8). A public database has
+no anonymous socket, so it cannot be listened to.
+
+A handler runs on the listener's thread, one change at a time. Changes caused
+by this ``Database``'s own writes are left out unless ``include_own=True`` --
+a script that writes in response to changes would otherwise feed itself, the
+same reason the JS client skips its self-writes.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import threading
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Callable
+
+from .errors import JotabaseError
+
+if TYPE_CHECKING:
+    from .client import Database
+
+log = logging.getLogger("jotabase.live")
+
+INITIAL_BACKOFF = 1.0
+MAX_BACKOFF = 30.0
+
+
+@dataclass
+class Change:
+    """What one notification brought: documents with ``seq`` past the last one seen."""
+
+    docs: list[dict[str, Any]]
+    last_seq: int
+    #: True when the frame carried the documents (``push``); False when they were read.
+    pushed: bool = False
+    #: True for the catch-up after a (re)connect rather than a notification.
+    catch_up: bool = False
+
+
+@dataclass
+class _State:
+    checkpoint: int
+    error: BaseException | None = None
+    connected: threading.Event = field(default_factory=threading.Event)
+
+
+def ws_url(db: "Database") -> str:
+    base = db.url
+    if base.startswith("https://"):
+        base = "wss://" + base[len("https://"):]
+    elif base.startswith("http://"):
+        base = "ws://" + base[len("http://"):]
+    return f"{base}/{db.name}/_ws"
+
+
+class Listener:
+    """A background connection calling ``handler(change)`` for each change.
+
+    Get one from :meth:`Database.on_change`. ``stop()`` ends it; it is also a
+    context manager. ``wait()`` blocks until it stops (or ``timeout``).
+    """
+
+    def __init__(
+        self,
+        db: "Database",
+        handler: Callable[[Change], Any],
+        since: int | None = None,
+        pull: bool = False,
+        include_own: bool = False,
+        on_error: Callable[[BaseException], Any] | None = None,
+    ):
+        if db.is_public or not db.credential:
+            raise JotabaseError("live changes need a key or a signed-in user; "
+                                "a public database has no anonymous socket")
+        self.db = db
+        self.handler = handler
+        self.pull = pull
+        self.include_own = include_own
+        self.on_error = on_error
+        self._stop = threading.Event()
+        self._ws = None
+        self._lock = threading.Lock()
+        self._state = _State(checkpoint=since if since is not None else -1)
+        self._thread = threading.Thread(target=self._run, name=f"jotabase-live-{db.name}", daemon=True)
+        self._thread.start()
+
+    # -- public --------------------------------------------------------------
+
+    @property
+    def checkpoint(self) -> int:
+        """The highest seq delivered (or skipped as nothing new)."""
+        return self._state.checkpoint
+
+    @property
+    def connected(self) -> bool:
+        return self._state.connected.is_set()
+
+    @property
+    def error(self) -> BaseException | None:
+        """Set when the listener stopped because the server refused it (401/403)."""
+        return self._state.error
+
+    def wait_connected(self, timeout: float | None = None) -> bool:
+        return self._state.connected.wait(timeout)
+
+    def stop(self) -> None:
+        self._stop.set()
+        with self._lock:
+            ws = self._ws
+        if ws is not None:
+            try:
+                ws.close()
+            except Exception:  # noqa: BLE001 - closing a dead socket
+                pass
+        if threading.current_thread() is not self._thread:
+            self._thread.join(timeout=10)
+
+    def wait(self, timeout: float | None = None) -> bool:
+        """Block until the listener stops; True if it did within ``timeout``."""
+        self._thread.join(timeout)
+        return not self._thread.is_alive()
+
+    def __enter__(self) -> "Listener":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.stop()
+
+    # -- loop ----------------------------------------------------------------
+
+    def _run(self) -> None:
+        from websockets.exceptions import InvalidStatus
+        from websockets.sync.client import connect
+
+        backoff = INITIAL_BACKOFF
+        while not self._stop.is_set():
+            try:
+                headers = {"Authorization": f"Bearer {self.db.credential}",
+                           "User-Agent": self.db._http.headers.get("User-Agent", "jotabase-python")}
+                with connect(ws_url(self.db), additional_headers=headers, open_timeout=15,
+                             close_timeout=2, max_size=None) as ws:
+                    with self._lock:
+                        self._ws = ws
+                    if self._stop.is_set():
+                        return
+                    self._state.connected.set()
+                    backoff = INITIAL_BACKOFF
+                    self._catch_up()
+                    for message in ws:
+                        if self._stop.is_set():
+                            return
+                        self._on_frame(message)
+            except InvalidStatus as e:
+                status = getattr(getattr(e, "response", None), "status_code", None)
+                if status in (401, 403):
+                    self._state.error = JotabaseError(f"live connection refused: {status}", status)
+                    self._report(self._state.error)
+                    return
+                self._report(e)
+            except Exception as e:  # noqa: BLE001 - reconnect on anything else
+                if self._stop.is_set():
+                    return
+                self._report(e)
+            finally:
+                self._state.connected.clear()
+                with self._lock:
+                    self._ws = None
+            if self._stop.wait(backoff):
+                return
+            backoff = min(backoff * 2, MAX_BACKOFF)
+
+    def _report(self, e: BaseException) -> None:
+        if self.on_error is not None:
+            try:
+                self.on_error(e)
+            except Exception:  # noqa: BLE001
+                log.exception("on_error raised")
+        else:
+            log.warning("jotabase live (%s): %s", self.db.name, e)
+
+    def _catch_up(self) -> None:
+        """At (re)connect: read what was missed. A fresh listener starts at now."""
+        if self._state.checkpoint < 0:
+            self._state.checkpoint = self.db.list_changes(since=2**62).checkpoint
+            return
+        self._read(catch_up=True)
+
+    def _on_frame(self, message: Any) -> None:
+        try:
+            msg = json.loads(message)
+        except (TypeError, ValueError):
+            return
+        if not isinstance(msg, dict) or msg.get("type") != "change":
+            return
+        last_seq = msg.get("last_seq")
+        if not isinstance(last_seq, int) or last_seq <= self._state.checkpoint:
+            return
+        if isinstance(msg.get("docs"), list):
+            docs = [d for d in msg["docs"] if isinstance(d, dict) and d.get("seq", 0) > self._state.checkpoint]
+            self._state.checkpoint = last_seq
+            self._deliver(Change(docs, last_seq, pushed=True))
+        else:
+            self._read()
+
+    def _read(self, catch_up: bool = False) -> None:
+        since = self._state.checkpoint
+        changes = self.db.fetch_changes(since=since)
+        # A listed segment can hold versions at or before `since`.
+        docs = [d for d in changes.items if d["seq"] > since]
+        self._state.checkpoint = max(since, changes.checkpoint)
+        if docs or not catch_up:
+            self._deliver(Change(docs, self._state.checkpoint, catch_up=catch_up))
+
+    def _deliver(self, change: Change) -> None:
+        if not self.include_own:
+            own = self.db._own_seqs
+            change.docs = [d for d in change.docs if d.get("seq") not in own]
+        if self.pull:
+            try:
+                self.db.pull()
+            except Exception as e:  # noqa: BLE001
+                self._report(e)
+        if not change.docs:
+            return
+        try:
+            self.handler(change)
+        except Exception:  # noqa: BLE001 - a handler's bug must not end the listener
+            log.exception("jotabase live handler raised")