jotabase 0.7.0__tar.gz

jotabase-0.7.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+.pytest_cache/
+*.egg-info/
+build/
+.venv/
+.jotabase/

jotabase-0.7.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.5
+Name: jotabase
+Version: 0.7.0
+Summary: Python client for jotaBase: read, write, local SQL with DuckDB and live changes.
+Project-URL: Homepage, https://jotabase.com
+Project-URL: Repository, https://github.com/jimv-dev/jbase
+Author: jotaBase
+License-Expression: ISC
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Database
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pyarrow>=15
+Requires-Dist: websockets>=13
+Provides-Extra: pandas
+Requires-Dist: pandas>=2.0; extra == 'pandas'
+Provides-Extra: polars
+Requires-Dist: polars>=1.0; extra == 'polars'
+Provides-Extra: sql
+Requires-Dist: duckdb>=1.1; extra == 'sql'
+Provides-Extra: test
+Requires-Dist: duckdb>=1.1; extra == 'test'
+Requires-Dist: pandas>=2.0; extra == 'test'
+Requires-Dist: polars>=1.0; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# jotabase
+
+Python client for [jotaBase](https://jotabase.com): sync, query and update your jotaBase databases
+from servers, scripts, notebooks and desktop apps.
+
+- **Read and write** a database with a secret key (servers and scripts) or a publishable key and a
+  signed-in user (apps, where access rules apply).
+- **Keep a copy on disk** that later syncs bring up to date, downloading only what changed.
+- **Query it with SQL** through DuckDB, one table per collection, with results as pandas or Polars
+  tables.
+- **React to changes** as they happen.
+
+```bash
+pip install jotabase                      # read, write, local copy, live changes
+pip install "jotabase[sql,pandas]"        # plus SQL with DuckDB, and pandas
+```
+
+Python 3.10 or newer.
+
+## Quick start
+
+```python
+import jotabase
+
+db = jotabase.connect("my-app", key="sk_live_...")   # your database's secret key
+
+# Write
+db.put("tasks", {"title": "Write the report", "points": 3}, id="t1")
+results = db.put_many("measurements", batch)        # split under the 1 MB request limit
+for r in results.failed:                            # refused by an access rule
+    print(r.id, r.error)
+db.delete("tasks", "t1")
+
+# Read everything, or only what changed since last time
+changes = db.fetch_changes()
+docs = changes.latest()                             # newest version of each, no deleted ones
+later = db.fetch_changes(since=changes.checkpoint)
+
+# Keep a copy in ./.jotabase/my-app/ and read it with no server
+db.pull()
+tasks = db.local().documents("tasks")
+
+# SQL over the copy (pip install "jotabase[sql]")
+df = db.sql("SELECT status, count(*) AS n FROM tasks GROUP BY status").df()   # pandas
+pl = db.sql("SELECT * FROM tasks WHERE points > ?", [3]).pl()                 # Polars
+
+# React to changes as they happen (a background thread)
+@db.on_change
+def changed(change):
+    for doc in change.docs:
+        print(doc["id"], doc["data"])
+```
+
+## Keys and users
+
+| You connect with | Who it is for | Access rules |
+|---|---|---|
+| `key="sk_..."` (secret) | servers, scripts, scheduled jobs | bypassed |
+| `key="pk_..."` (publishable), then `db.sign_in(email, password)` | apps and desktop apps | applied to the user's roles |
+| no key, `jotabase.connect("@handle/name")` | someone's public database | read-only, no live changes |
+
+Never ship a secret key inside an app that runs on someone else's machine. Keys are created in the
+dashboard at [app.jotabase.com](https://app.jotabase.com).
+
+## Errors
+
+A refused request raises `jotabase.JotabaseError` with `.status` (401/403 means the key or the
+login, anything else is worth a retry) and `.code`. A document an access rule refuses does **not**
+raise: it comes back in `results.failed` with the reason, while the rest of the batch is written.
+
+## Links
+
+- [jotaBase](https://jotabase.com) and the [dashboard](https://app.jotabase.com)
+- [Design notes for this package](https://github.com/jimv-dev/jbase/blob/main/docs/PYTHON-CLIENT.md)
+- The JavaScript client: [`@jotabase/client`](https://www.npmjs.com/package/@jotabase/client)

jotabase-0.7.0/README.md

@@ -0,0 +1,75 @@
+# jotabase
+
+Python client for [jotaBase](https://jotabase.com): sync, query and update your jotaBase databases
+from servers, scripts, notebooks and desktop apps.
+
+- **Read and write** a database with a secret key (servers and scripts) or a publishable key and a
+  signed-in user (apps, where access rules apply).
+- **Keep a copy on disk** that later syncs bring up to date, downloading only what changed.
+- **Query it with SQL** through DuckDB, one table per collection, with results as pandas or Polars
+  tables.
+- **React to changes** as they happen.
+
+```bash
+pip install jotabase                      # read, write, local copy, live changes
+pip install "jotabase[sql,pandas]"        # plus SQL with DuckDB, and pandas
+```
+
+Python 3.10 or newer.
+
+## Quick start
+
+```python
+import jotabase
+
+db = jotabase.connect("my-app", key="sk_live_...")   # your database's secret key
+
+# Write
+db.put("tasks", {"title": "Write the report", "points": 3}, id="t1")
+results = db.put_many("measurements", batch)        # split under the 1 MB request limit
+for r in results.failed:                            # refused by an access rule
+    print(r.id, r.error)
+db.delete("tasks", "t1")
+
+# Read everything, or only what changed since last time
+changes = db.fetch_changes()
+docs = changes.latest()                             # newest version of each, no deleted ones
+later = db.fetch_changes(since=changes.checkpoint)
+
+# Keep a copy in ./.jotabase/my-app/ and read it with no server
+db.pull()
+tasks = db.local().documents("tasks")
+
+# SQL over the copy (pip install "jotabase[sql]")
+df = db.sql("SELECT status, count(*) AS n FROM tasks GROUP BY status").df()   # pandas
+pl = db.sql("SELECT * FROM tasks WHERE points > ?", [3]).pl()                 # Polars
+
+# React to changes as they happen (a background thread)
+@db.on_change
+def changed(change):
+    for doc in change.docs:
+        print(doc["id"], doc["data"])
+```
+
+## Keys and users
+
+| You connect with | Who it is for | Access rules |
+|---|---|---|
+| `key="sk_..."` (secret) | servers, scripts, scheduled jobs | bypassed |
+| `key="pk_..."` (publishable), then `db.sign_in(email, password)` | apps and desktop apps | applied to the user's roles |
+| no key, `jotabase.connect("@handle/name")` | someone's public database | read-only, no live changes |
+
+Never ship a secret key inside an app that runs on someone else's machine. Keys are created in the
+dashboard at [app.jotabase.com](https://app.jotabase.com).
+
+## Errors
+
+A refused request raises `jotabase.JotabaseError` with `.status` (401/403 means the key or the
+login, anything else is worth a retry) and `.code`. A document an access rule refuses does **not**
+raise: it comes back in `results.failed` with the reason, while the rest of the batch is written.
+
+## Links
+
+- [jotaBase](https://jotabase.com) and the [dashboard](https://app.jotabase.com)
+- [Design notes for this package](https://github.com/jimv-dev/jbase/blob/main/docs/PYTHON-CLIENT.md)
+- The JavaScript client: [`@jotabase/client`](https://www.npmjs.com/package/@jotabase/client)

jotabase-0.7.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "jotabase"
+dynamic = ["version"]
+description = "Python client for jotaBase: read, write, local SQL with DuckDB and live changes."
+readme = "README.md"
+license = "ISC"
+requires-python = ">=3.10"
+authors = [{ name = "jotaBase" }]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Database",
+]
+dependencies = [
+  "httpx>=0.27",
+  "pyarrow>=15",
+  "websockets>=13",
+]
+
+[project.optional-dependencies]
+sql = ["duckdb>=1.1"]
+pandas = ["pandas>=2.0"]
+polars = ["polars>=1.0"]
+test = ["pytest>=8", "duckdb>=1.1", "pandas>=2.0", "polars>=1.0"]
+
+[project.urls]
+Homepage = "https://jotabase.com"
+Repository = "https://github.com/jimv-dev/jbase"
+
+# The version lives in one place, src/jotabase/__init__.py, and
+# scripts/set-version.mjs writes it there together with the npm packages.
+[tool.hatch.version]
+path = "src/jotabase/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/jotabase"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

jotabase-0.7.0/src/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-0.7.0/src/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-0.7.0/src/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/*``)."""