gnomon-postgres 1.0.0__tar.gz

gnomon_postgres-1.0.0/LICENSE

@@ -0,0 +1,17 @@
+PostgreSQL License
+
+Copyright (c) 2026, The Gnomon Contributors
+
+Permission to use, copy, modify, and distribute this software and its documentation for any
+purpose, without fee, and without a written agreement is hereby granted, provided that the
+above copyright notice and this paragraph and the following two paragraphs appear in all copies.
+
+IN NO EVENT SHALL THE GNOMON CONTRIBUTORS BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL,
+INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS, ARISING OUT OF THE USE OF THIS
+SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE GNOMON CONTRIBUTORS HAVE BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.
+
+THE GNOMON CONTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED
+HEREUNDER IS ON AN "AS IS" BASIS, AND THE GNOMON CONTRIBUTORS HAVE NO OBLIGATIONS TO PROVIDE
+MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.

gnomon_postgres-1.0.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: gnomon-postgres
+Version: 1.0.0
+Summary: Branches, time travel and merges for PostgreSQL apps: psycopg helpers, SQLAlchemy, Django and pytest fixtures for the gnomon extension
+License-Expression: PostgreSQL
+Project-URL: Homepage, https://gnomon.bitsinfra.com/
+Project-URL: Repository, https://github.com/bitsinfra/gnomon
+Project-URL: Issues, https://github.com/bitsinfra/gnomon/issues
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: psycopg>=3.1
+Provides-Extra: sqlalchemy
+Requires-Dist: sqlalchemy>=2; extra == "sqlalchemy"
+Provides-Extra: django
+Requires-Dist: django>=4.2; extra == "django"
+Provides-Extra: asyncpg
+Requires-Dist: asyncpg>=0.29; extra == "asyncpg"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# gnomon-postgres (Python)
+
+Branches, time travel and merges for PostgreSQL apps on the gnomon extension: the SDK (runs for
+agents and tasks, review, the core), psycopg helpers, SQLAlchemy and Django, and pytest fixtures
+with snapshots. `import gnomon`.
+
+```python
+from gnomon import Gnomon
+
+gn = Gnomon(app="dbname=shop user=shop_app", runs="dbname=shop user=shop_runs")
+with gn.start_run("Refund order 3", actor="support-bot") as run:   # a branch for this task
+    run.sql("update orders set status = 'refunded' where id = 3")
+    if run.summary()["checks"]["passed"]: run.merge()
+    else: run.submit("Refund order 3")                               # a change request instead
+```
+
+Leaving the `with` block without `merge()` or `submit()` discards the branch. `run.url(base)` and
+`run.connection(base)` give a tool a connection string, or a psycopg connection, pinned to the run
+(a login of the run's own, confined to its branch, dropped when the run ends). With asyncpg:
+`AsyncGnomon(app=asyncpg_source(pool), runs=asyncpg_source(runs_pool))` (`from gnomon.asyncpg import
+asyncpg_source`; the `asyncpg` extra). `AsyncGnomon` is the
+same API for `psycopg.AsyncConnection` (the sync client is generated from it, so they cannot
+drift). `gn.requests`, `gn.branches`, `history`, `blame`, `revert`, `status()` and `doctor()` are
+the review and core layers. Tools for agent frameworks bound to one run:
+`gnomon.tools.anthropic_tools(run)`, `openai_agents_tools(run)`, `langchain_tools(run)`,
+`mcp_handler(run)`. The two logins, the envelope and the errors are as in the TypeScript SDK
+([sdk/ts/README.md](../../sdk/ts/README.md)); both pass the same conformance scenarios
+([sdk/spec](../../sdk/spec)).
+
+## Helpers
+
+```python
+import gnomon, psycopg
+conn = psycopg.connect(gnomon.branch_dsn("dbname=shop", "feature"))   # sessions start on a branch
+with gnomon.branch(conn, "feature"): ...                               # or switch one connection
+opts = gnomon.connection_options(admin_conn, "feature")                # what the database says the
+                                                                       # branch needs (schema versions, masks)
+```
+
+`use`, `begin` (one transaction, for poolers), `create_branch`, `create_scratch`, `drop_branch`,
+`diff`, `merge`. SQLAlchemy: `gnomon.sqlalchemy.branch_engine(url, branch)` and
+`attach_branch(engine, get_branch)` (each transaction on the branch a callable names). Django:
+`gnomon.django.BranchMiddleware` (a branch per request from `X-Gnomon-Branch`).
+
+## Tests on branches
+
+```python
+def test_signup(gnomon_conn, gnomon_snapshot):     # a psycopg connection on a fresh scratch branch
+    signup(gnomon_conn, "a@x.io")
+    gnomon_snapshot.assert_match(gnomon_conn)      # the branch's diff against a stored file
+```
+
+`GNOMON_TEST_DSN=... pytest` (the plugin loads itself when the package is installed;
+`--gnomon-update-snapshots` records, `--gnomon-keep` keeps the branches).
+`gnomon.testing.assert_no_changes` and `assert_changed` check a branch's diff directly.
+
+Install: `pip install gnomon-postgres` (extras: `sqlalchemy`, `django`, `test`).

gnomon_postgres-1.0.0/README.md

@@ -0,0 +1,57 @@
+# gnomon-postgres (Python)
+
+Branches, time travel and merges for PostgreSQL apps on the gnomon extension: the SDK (runs for
+agents and tasks, review, the core), psycopg helpers, SQLAlchemy and Django, and pytest fixtures
+with snapshots. `import gnomon`.
+
+```python
+from gnomon import Gnomon
+
+gn = Gnomon(app="dbname=shop user=shop_app", runs="dbname=shop user=shop_runs")
+with gn.start_run("Refund order 3", actor="support-bot") as run:   # a branch for this task
+    run.sql("update orders set status = 'refunded' where id = 3")
+    if run.summary()["checks"]["passed"]: run.merge()
+    else: run.submit("Refund order 3")                               # a change request instead
+```
+
+Leaving the `with` block without `merge()` or `submit()` discards the branch. `run.url(base)` and
+`run.connection(base)` give a tool a connection string, or a psycopg connection, pinned to the run
+(a login of the run's own, confined to its branch, dropped when the run ends). With asyncpg:
+`AsyncGnomon(app=asyncpg_source(pool), runs=asyncpg_source(runs_pool))` (`from gnomon.asyncpg import
+asyncpg_source`; the `asyncpg` extra). `AsyncGnomon` is the
+same API for `psycopg.AsyncConnection` (the sync client is generated from it, so they cannot
+drift). `gn.requests`, `gn.branches`, `history`, `blame`, `revert`, `status()` and `doctor()` are
+the review and core layers. Tools for agent frameworks bound to one run:
+`gnomon.tools.anthropic_tools(run)`, `openai_agents_tools(run)`, `langchain_tools(run)`,
+`mcp_handler(run)`. The two logins, the envelope and the errors are as in the TypeScript SDK
+([sdk/ts/README.md](../../sdk/ts/README.md)); both pass the same conformance scenarios
+([sdk/spec](../../sdk/spec)).
+
+## Helpers
+
+```python
+import gnomon, psycopg
+conn = psycopg.connect(gnomon.branch_dsn("dbname=shop", "feature"))   # sessions start on a branch
+with gnomon.branch(conn, "feature"): ...                               # or switch one connection
+opts = gnomon.connection_options(admin_conn, "feature")                # what the database says the
+                                                                       # branch needs (schema versions, masks)
+```
+
+`use`, `begin` (one transaction, for poolers), `create_branch`, `create_scratch`, `drop_branch`,
+`diff`, `merge`. SQLAlchemy: `gnomon.sqlalchemy.branch_engine(url, branch)` and
+`attach_branch(engine, get_branch)` (each transaction on the branch a callable names). Django:
+`gnomon.django.BranchMiddleware` (a branch per request from `X-Gnomon-Branch`).
+
+## Tests on branches
+
+```python
+def test_signup(gnomon_conn, gnomon_snapshot):     # a psycopg connection on a fresh scratch branch
+    signup(gnomon_conn, "a@x.io")
+    gnomon_snapshot.assert_match(gnomon_conn)      # the branch's diff against a stored file
+```
+
+`GNOMON_TEST_DSN=... pytest` (the plugin loads itself when the package is installed;
+`--gnomon-update-snapshots` records, `--gnomon-keep` keeps the branches).
+`gnomon.testing.assert_no_changes` and `assert_changed` check a branch's diff directly.
+
+Install: `pip install gnomon-postgres` (extras: `sqlalchemy`, `django`, `test`).

gnomon_postgres-1.0.0/gnomon/__init__.py

@@ -0,0 +1,140 @@
+"""Helpers for apps on a PostgreSQL database with the gnomon extension.
+
+Choosing a branch is plain SQL. In SQL-only mode it takes the setting *and* the routing
+search_path, which ``gnomon.use()`` (session) and ``gnomon.begin()`` (one transaction, safe behind
+transaction poolers) set together; with the C module loaded, ``SET gnomon.branch`` alone routes.
+"""
+from __future__ import annotations
+
+import contextlib
+import os
+import secrets
+from typing import Iterator, Optional
+from urllib.parse import quote
+
+__all__ = [
+    "routing_schema", "branch_options", "connection_options", "branch_dsn", "use", "begin", "create_branch", "create_scratch",
+    "drop_branch", "merge", "diff", "branch", "connect",
+    # the SDK
+    "Gnomon", "AsyncGnomon", "Run", "AsyncRun", "GnomonError",
+]
+
+
+def routing_schema(schema: str = "public", *, scratch: bool = False) -> str:
+    """The routing schema of a user schema; scratch branches have their own (``__s``)."""
+    return f"gnomon_r_{schema}" + ("__s" if scratch else "")
+
+
+def branch_options(branch: str, *, c_module: bool = False, schemas: tuple[str, ...] = ("public",),
+                   as_of: Optional[str] = None, scratch: bool = False) -> str:
+    """The libpq ``options`` value that puts a connection on a branch.
+    ``scratch``: the branch is a scratch branch (it is read through the scratch routing schemas)."""
+    opts = [f"-c gnomon.branch={branch}"]
+    if as_of:
+        opts.append(f"-c gnomon.as_of={as_of}")
+    if not c_module:
+        path = ",".join(p for s in schemas for p in (routing_schema(s, scratch=scratch), s))
+        opts.append(f"-c search_path={path}")
+    return " ".join(opts)
+
+
+def connection_options(conn, branch: str, *, c_module: bool = False) -> str:
+    """The ``options`` value the database computes for ``branch`` (``gnomon.connection_options``):
+    unlike :func:`branch_options`, it knows the branch's kind, a confined role's mask profile and
+    the branch's schema version."""
+    return conn.execute("select gnomon.connection_options(%s, %s)", (branch, c_module)).fetchone()[0]
+
+
+def branch_dsn(dsn: str, branch: str, *, options: Optional[str] = None, **kw) -> str:
+    """A connection string (URL or key=value) whose sessions start on ``branch``. ``options``: a
+    value from :func:`connection_options` instead of the one built here."""
+    opts = options or branch_options(branch, **kw)
+    if "://" in dsn:
+        sep = "&" if "?" in dsn else "?"
+        return f"{dsn}{sep}options={quote(opts)}"
+    return f"{dsn} options='{opts}'"
+
+
+def use(conn, branch: str = "main", as_of: Optional[str] = None) -> str:
+    """Put a psycopg connection's session on a branch (``main`` resets it)."""
+    with conn.cursor() as cur:
+        cur.execute("select gnomon.use(%s, %s)", (branch, as_of))
+        return cur.fetchone()[0]
+
+
+def begin(conn, branch: str, as_of: Optional[str] = None) -> None:
+    """Put the current transaction on a branch (SET LOCAL semantics, for poolers)."""
+    with conn.cursor() as cur:
+        cur.execute("select gnomon.begin(%s, %s)", (branch, as_of))
+
+
+def create_branch(conn, name: str, parent: str = "main", *, scratch: bool = False,
+                  at: Optional[str] = None) -> int:
+    with conn.cursor() as cur:
+        cur.execute("select gnomon.create_branch(%s, %s, %s, %s)", (name, parent, "scratch" if scratch else "logged", at))
+        return cur.fetchone()[0]
+
+
+def create_scratch(conn, prefix: str = "test", parent: str = "main") -> str:
+    name = f"{prefix}-{os.getpid():x}-{secrets.token_hex(4)}"
+    create_branch(conn, name, parent, scratch=True)
+    return name
+
+
+def drop_branch(conn, name: str, cascade: bool = True) -> None:
+    with conn.cursor() as cur:
+        cur.execute("select gnomon.drop_branch(%s, %s)", (name, cascade))
+
+
+def merge(conn, source: str, target: Optional[str] = None) -> dict:
+    with conn.cursor() as cur:
+        cur.execute("select gnomon.merge(%s, %s)", (source, target))
+        mid = cur.fetchone()[0]
+        cur.execute("select id, status, stats from gnomon.merge where id = %s", (mid,))
+        i, status, stats = cur.fetchone()
+        return {"id": i, "status": status, "stats": stats}
+
+
+def diff(conn, a: str, b: Optional[str] = None) -> list[dict]:
+    with conn.cursor() as cur:
+        cur.execute("select tbl::text, key, kind, col, old, new from gnomon.diff(%s, %s)", (a, b))
+        cols = ["table", "key", "kind", "col", "old", "new"]
+        return [dict(zip(cols, r)) for r in cur.fetchall()]
+
+
+@contextlib.contextmanager
+def branch(conn, name: str, as_of: Optional[str] = None) -> Iterator[None]:
+    """``with gnomon.branch(conn, "feature"):`` - the session reads and writes the branch inside."""
+    use(conn, name, as_of)
+    try:
+        yield
+    finally:
+        if not conn.closed:
+            if conn.info.transaction_status != 0:  # not idle: leave the caller's transaction alone
+                conn.rollback()
+            use(conn, "main")
+
+
+def connect(dsn: str, branch_name: Optional[str] = None, **kw):
+    """psycopg.connect, optionally starting on a branch."""
+    import psycopg
+
+    conn = psycopg.connect(dsn, **kw)
+    if branch_name:
+        use(conn, branch_name)
+    return conn
+
+
+# The SDK: runs, review, core. Imported lazily so the helpers above need
+# nothing but psycopg.
+def __getattr__(name):
+    if name in ("Gnomon", "Run", "Request", "Branches"):
+        from . import client
+        return getattr(client, name)
+    if name in ("AsyncGnomon", "AsyncRun", "AsyncRequest", "AsyncBranches"):
+        from . import aio
+        return getattr(aio, name)
+    if name in ("GnomonError",):
+        from . import errors
+        return getattr(errors, name)
+    raise AttributeError(name)

gnomon_postgres-1.0.0/gnomon/_util.py

@@ -0,0 +1,82 @@
+"""Lossless JSON and the statement splitter (shared by the sync and async clients)."""
+from __future__ import annotations
+
+import json
+import re
+from decimal import Decimal
+from typing import Any
+
+
+def parse_json(text: Any) -> Any:
+    """JSON text to Python: integers stay exact (int), decimals become Decimal (spec: Values)."""
+    if text is None:
+        return None
+    if not isinstance(text, str):
+        return text
+    return json.loads(text, parse_float=Decimal)
+
+
+def stable_json(v: Any) -> str:
+    """JSON text with object keys sorted, compact, as the TypeScript SDK writes it (snapshots, digests)."""
+    def default(x):
+        return str(x)
+    return json.dumps(_num(v), sort_keys=True, separators=(",", ":"), default=default, ensure_ascii=False)
+
+
+def _num(v):
+    if isinstance(v, Decimal):
+        return int(v) if v == v.to_integral_value() else float(v) if str(float(v)) == str(v) else str(v)
+    if isinstance(v, dict):
+        return {k: _num(x) for k, x in v.items()}
+    if isinstance(v, list):
+        return [_num(x) for x in v]
+    return v
+
+
+_DOLLAR = re.compile(r"\$([A-Za-z_][A-Za-z_0-9]*)?\$")
+
+
+def split_sql(sql: str) -> list[str]:
+    """Top-level statements of a script (the port of tools/sqlsplit.py)."""
+    out, buf, i, n = [], [], 0, len(sql)
+    while i < n:
+        c = sql[i]
+        if c == "-" and sql.startswith("--", i):
+            j = sql.find("\n", i)
+            j = n if j < 0 else j
+            buf.append(sql[i:j]); i = j; continue
+        if c == "/" and sql.startswith("/*", i):
+            j = sql.find("*/", i + 2)
+            j = n if j < 0 else j + 2
+            buf.append(sql[i:j]); i = j; continue
+        if c == "'":
+            j = i + 1
+            while j < n:
+                if sql[j] == "'" and j + 1 < n and sql[j + 1] == "'":
+                    j += 2; continue
+                if sql[j] == "'":
+                    break
+                j += 1
+            buf.append(sql[i:j + 1]); i = j + 1; continue
+        if c == '"':
+            j = sql.find('"', i + 1)
+            j = n - 1 if j < 0 else j
+            buf.append(sql[i:j + 1]); i = j + 1; continue
+        if c == "$":
+            m = _DOLLAR.match(sql, i)
+            if m:
+                tag = m.group(0)
+                j = sql.find(tag, i + len(tag))
+                j = n if j < 0 else j + len(tag)
+                buf.append(sql[i:j]); i = j; continue
+        if c == ";":
+            buf.append(";"); out.append("".join(buf)); buf = []; i += 1; continue
+        buf.append(c); i += 1
+    rest = "".join(buf)
+    if rest.strip():
+        out.append(rest)
+    def empty(s):
+        s = re.sub(r"--[^\n]*", "", s)
+        s = re.sub(r"/\*.*?\*/", "", s, flags=re.S)
+        return s.replace(";", "").strip() == ""
+    return [s for s in out if not empty(s)]