From 8483aeb7688968eb154c336568ddfd579b63e5f6 Mon Sep 17 00:00:00 2001 From: Felipe Gutierrez Date: Fri, 6 Nov 2026 17:53:02 -0500 Subject: [PATCH 1/4] Add ideas-board Python example demonstrating @crdb_retry (unit+integration) --- examples/ideas-board/.gitignore | 4 + examples/ideas-board/README.md | 89 ++++++++++++++++++++++ examples/ideas-board/conftest.py | 6 ++ examples/ideas-board/crdb_container.py | 55 ++++++++++++++ examples/ideas-board/idea.py | 22 ++++++ examples/ideas-board/main.py | 95 ++++++++++++++++++++++++ examples/ideas-board/repository.py | 58 +++++++++++++++ examples/ideas-board/requirements.txt | 10 +++ examples/ideas-board/service.py | 64 ++++++++++++++++ examples/ideas-board/test_concurrency.py | 83 +++++++++++++++++++++ examples/ideas-board/test_unit.py | 69 +++++++++++++++++ 11 files changed, 555 insertions(+) create mode 100644 examples/ideas-board/.gitignore create mode 100644 examples/ideas-board/README.md create mode 100644 examples/ideas-board/conftest.py create mode 100644 examples/ideas-board/crdb_container.py create mode 100644 examples/ideas-board/idea.py create mode 100644 examples/ideas-board/main.py create mode 100644 examples/ideas-board/repository.py create mode 100644 examples/ideas-board/requirements.txt create mode 100644 examples/ideas-board/service.py create mode 100644 examples/ideas-board/test_concurrency.py create mode 100644 examples/ideas-board/test_unit.py diff --git a/examples/ideas-board/.gitignore b/examples/ideas-board/.gitignore new file mode 100644 index 0000000..17cd2fc --- /dev/null +++ b/examples/ideas-board/.gitignore @@ -0,0 +1,4 @@ +.venv/ +__pycache__/ +*.pyc +.pytest_cache/ diff --git a/examples/ideas-board/README.md b/examples/ideas-board/README.md new file mode 100644 index 0000000..aa77d2f --- /dev/null +++ b/examples/ideas-board/README.md @@ -0,0 +1,89 @@ +# Concurrent Ideas Board (Python) + +The Python twin of the Spring/.NET/Java/Go fundamentals demos. It proves the +library's hero feature: **automatic retry on serialization conflicts +(SQLSTATE 40001)** via the `@crdb_retry` decorator. + +## What it shows + +One idea row, many concurrent upvotes. Each upvote is a read-modify-write +(`SELECT votes` → `votes + 1` → `UPDATE`) under **SERIALIZABLE** isolation, so +colliding upvotes force CockroachDB to raise `40001`. + +- `upvote_without_retry()` — no decorator. Conflicts propagate, votes are **lost**. +- `upvote()` — wrapped in `@crdb_retry(...)`. The decorator re-runs the whole + function in a fresh transaction on `40001`, so **every vote lands**. + +``` +PLAIN @crdb_retry OFF : 2/25 votes landed (23 lost to 40001) +RETRY @crdb_retry ON : 25/25 votes landed (0 failures) +``` + +## Files + +| File | Role | +|------|------| +| `idea.py` | `Idea` dataclass (id, text, votes) | +| `repository.py` | psycopg read-modify-write helpers taking a cursor | +| `service.py` | `upvote_without_retry` (plain) and `upvote` (`@crdb_retry`) | +| `main.py` | seed one idea, fire N concurrent upvotes per path, print both | +| `test_unit.py` | fast unit test, no Docker (mocked psycopg) | +| `test_concurrency.py` | integration test, real CockroachDB via testcontainers | +| `crdb_container.py` | helper that boots an insecure CockroachDB container | + +## Prerequisites + +- Python 3.12+ +- Docker (only for `main.py`'s throwaway cluster and the integration test) + +## Install + +The library ships on an anonymous PEP 503 feed, not public PyPI: + +```bash +python -m venv .venv +source .venv/bin/activate +pip install -r requirements.txt +``` + +`requirements.txt` pins the **published** `cockroachdb==0.1.2` (plus +`cockroachdb-testing==0.1.1`) and carries the `--extra-index-url` line for the +feed. A single-package install looks like: + +```bash +pip install 'cockroachdb==0.1.2' \ + --extra-index-url https://cockroachlabs.github.io/cockroachdb-python-library/simple/ +``` + +## Run + +```bash +# Uses $CRDB_DSN if set, otherwise spins up a throwaway container (needs Docker). +python main.py + +# Point at your own cluster instead: +CRDB_DSN=postgresql://root@localhost:26257/defaultdb python main.py +``` + +## Test + +```bash +pytest # unit always runs; integration needs Docker +pytest test_unit.py # fast path only, no container +``` + +The unit test runs with **no container**. The integration test boots a real +CockroachDB container and asserts the retry path lands exactly 60 votes while +the plain path does not. + +> Container note: the published `cockroachdb-testing` fixture and the +> `testcontainers` cockroachdb module boot CockroachDB in *secure* mode, which +> needs a client certificate this example does not ship (and psycopg3 cannot +> parse the module's `cockroachdb+psycopg2://` URL). So `crdb_container.py` runs +> the same image in `--insecure` mode and yields a plain `postgresql://` DSN — +> the exact connection style the library's own examples use. + +> Source note: this example lives inside the `cockroachdb-python-library` +> checkout, so its tests were validated against the **local source** via +> `pip install -e packages/cockroachdb packages/cockroachdb-core`. +> Customers use the pinned published install above. diff --git a/examples/ideas-board/conftest.py b/examples/ideas-board/conftest.py new file mode 100644 index 0000000..384e0b1 --- /dev/null +++ b/examples/ideas-board/conftest.py @@ -0,0 +1,6 @@ +"""Make the flat example modules importable when running pytest from here.""" + +import os +import sys + +sys.path.insert(0, os.path.dirname(__file__)) diff --git a/examples/ideas-board/crdb_container.py b/examples/ideas-board/crdb_container.py new file mode 100644 index 0000000..fe89875 --- /dev/null +++ b/examples/ideas-board/crdb_container.py @@ -0,0 +1,55 @@ +"""Throwaway insecure CockroachDB via testcontainers. + +The published `cockroachdb-testing` fixture and the `testcontainers` cockroachdb +module both boot CockroachDB in SECURE mode, which requires a client certificate +this example does not ship (and psycopg3 cannot parse the module's +`cockroachdb+psycopg2://` URL). So we run the same CockroachDB image in +`--insecure` mode via the generic testcontainers API and hand back a plain +`postgresql://` DSN — identical to how the library's own examples connect +(e.g. `postgresql://root@localhost:26257/defaultdb`). +""" + +from __future__ import annotations + +import contextlib +import time +from collections.abc import Iterator + +import psycopg + +IMAGE = "cockroachdb/cockroach:v24.3.0" + + +@contextlib.contextmanager +def insecure_crdb() -> Iterator[str]: + """Start an insecure single-node CockroachDB; yield a psycopg DSN.""" + from testcontainers.core.container import DockerContainer + from testcontainers.core.waiting_utils import wait_for_logs + + container = ( + DockerContainer(IMAGE) + .with_command("start-single-node --insecure") + .with_exposed_ports(26257) + ) + container.start() + try: + wait_for_logs(container, "CockroachDB node starting", timeout=90) + host = container.get_container_host_ip() + port = container.get_exposed_port(26257) + dsn = f"postgresql://root@{host}:{port}/defaultdb?sslmode=disable" + _wait_ready(dsn) + yield dsn + finally: + container.stop() + + +def _wait_ready(dsn: str, attempts: int = 30) -> None: + for _ in range(attempts): + try: + with psycopg.connect(dsn, connect_timeout=3) as conn: + conn.execute("SELECT 1") + return + except psycopg.OperationalError: + time.sleep(1) + msg = "CockroachDB did not become ready in time" + raise RuntimeError(msg) diff --git a/examples/ideas-board/idea.py b/examples/ideas-board/idea.py new file mode 100644 index 0000000..2957c45 --- /dev/null +++ b/examples/ideas-board/idea.py @@ -0,0 +1,22 @@ +"""Domain entity for the Concurrent Ideas Board example.""" + +from __future__ import annotations + +# tag::entity[] +from dataclasses import dataclass + + +@dataclass +class Idea: + """A single idea on the board. + + Attributes: + id: Primary key assigned by CockroachDB. + text: The idea's text. + votes: Running upvote count — the hotly-contended column. + """ + + id: int + text: str + votes: int +# end::entity[] diff --git a/examples/ideas-board/main.py b/examples/ideas-board/main.py new file mode 100644 index 0000000..1a032f8 --- /dev/null +++ b/examples/ideas-board/main.py @@ -0,0 +1,95 @@ +"""Runnable demo: concurrent upvotes on one hot row, plain vs. @crdb_retry. + +Seeds a single idea, then fires N concurrent upvotes through the plain path +(votes get lost to 40001) and the retry path (every vote lands). + +Connection: + - Set CRDB_DSN to point at a running cluster, e.g. + CRDB_DSN=postgresql://root@localhost:26257/defaultdb + - Or leave it unset and the demo spins up a throwaway CockroachDB + container via cockroachdb-testing (requires Docker). + +Usage: + python main.py +""" + +from __future__ import annotations + +import contextlib +import os +import threading +from collections.abc import Iterator + +import repository +import service + + +@contextlib.contextmanager +def _dsn() -> Iterator[str]: + """Yield a psycopg DSN — from CRDB_DSN, or a throwaway container.""" + env = os.environ.get("CRDB_DSN") + if env: + yield env + return + from crdb_container import insecure_crdb + + with insecure_crdb() as dsn: + yield dsn + + +# tag::runner[] +def _hammer(dsn: str, idea_id: int, fn, votes: int) -> int: + """Fire *votes* concurrent upvotes through *fn*; return the failure count. + + A barrier releases every thread at the same instant so the read-modify-write + windows overlap and CockroachDB is forced to serialize them. + """ + barrier = threading.Barrier(votes) + failures: list[Exception] = [] + lock = threading.Lock() + + def worker() -> None: + barrier.wait() + try: + fn(dsn, idea_id) + except Exception as exc: # noqa: BLE001 — count, don't crash the demo + with lock: + failures.append(exc) + + threads = [threading.Thread(target=worker) for _ in range(votes)] + for t in threads: + t.start() + for t in threads: + t.join() + return len(failures) + + +def main() -> None: + votes = 25 + with _dsn() as dsn, __import__("psycopg").connect(dsn, autocommit=True) as conn: + with conn.cursor() as cur: + repository.create_schema(cur) + idea_id = repository.seed(cur, "Add dark mode to the dashboard") + + print(f"Seeded idea #{idea_id}; firing {votes} concurrent upvotes per path.\n") + + # Plain path — no retry. Conflicts raise 40001 and those votes are lost. + failures = _hammer(dsn, idea_id, service.upvote_without_retry, votes) + with conn.cursor() as cur: + plain_total = repository.current_votes(cur, idea_id) + print(f"PLAIN @crdb_retry OFF : {plain_total}/{votes} votes landed " + f"({failures} lost to 40001)") + + # Reset, then the retry path — every vote eventually commits. + with conn.cursor() as cur: + repository.reset(cur, idea_id) + failures = _hammer(dsn, idea_id, service.upvote, votes) + with conn.cursor() as cur: + retry_total = repository.current_votes(cur, idea_id) + print(f"RETRY @crdb_retry ON : {retry_total}/{votes} votes landed " + f"({failures} failures)") +# end::runner[] + + +if __name__ == "__main__": + main() diff --git a/examples/ideas-board/repository.py b/examples/ideas-board/repository.py new file mode 100644 index 0000000..a3a69a2 --- /dev/null +++ b/examples/ideas-board/repository.py @@ -0,0 +1,58 @@ +"""psycopg read-modify-write helpers for the ideas board. + +Every helper takes a psycopg cursor (or connection) so the caller owns +transaction and connection lifecycle — the pattern @crdb_retry requires, +since the decorator re-executes the whole operation on a serialization +conflict and each attempt needs a fresh transaction. +""" + +from __future__ import annotations + +from typing import TYPE_CHECKING + +from idea import Idea + +if TYPE_CHECKING: + import psycopg + + +# tag::repo[] +def create_schema(cur: psycopg.Cursor) -> None: + """Create the ideas table if it does not already exist.""" + cur.execute( + "CREATE TABLE IF NOT EXISTS ideas (" + " id INT PRIMARY KEY DEFAULT unique_rowid()," + " text STRING NOT NULL," + " votes INT NOT NULL DEFAULT 0" + ")" + ) + + +def seed(cur: psycopg.Cursor, text: str) -> int: + """Insert one idea with zero votes and return its id.""" + cur.execute("INSERT INTO ideas (text) VALUES (%s) RETURNING id", (text,)) + return cur.fetchone()[0] + + +def find(cur: psycopg.Cursor, idea_id: int) -> Idea | None: + """Return the full Idea row, or None if it does not exist.""" + cur.execute("SELECT id, text, votes FROM ideas WHERE id = %s", (idea_id,)) + row = cur.fetchone() + return Idea(id=row[0], text=row[1], votes=row[2]) if row else None + + +def current_votes(cur: psycopg.Cursor, idea_id: int) -> int: + """Read the current vote count — the READ half of read-modify-write.""" + cur.execute("SELECT votes FROM ideas WHERE id = %s", (idea_id,)) + return cur.fetchone()[0] + + +def update_votes(cur: psycopg.Cursor, idea_id: int, votes: int) -> None: + """Write an absolute vote count — the WRITE half of read-modify-write.""" + cur.execute("UPDATE ideas SET votes = %s WHERE id = %s", (votes, idea_id)) + + +def reset(cur: psycopg.Cursor, idea_id: int, votes: int = 0) -> None: + """Reset an idea's vote count (used to re-run the two paths cleanly).""" + cur.execute("UPDATE ideas SET votes = %s WHERE id = %s", (votes, idea_id)) +# end::repo[] diff --git a/examples/ideas-board/requirements.txt b/examples/ideas-board/requirements.txt new file mode 100644 index 0000000..e08e4dd --- /dev/null +++ b/examples/ideas-board/requirements.txt @@ -0,0 +1,10 @@ +# Concurrent Ideas Board example — dependencies +# +# Published install (what the tutorial/docs show): the library ships on an +# anonymous PEP 503 feed, NOT public PyPI. +--extra-index-url https://cockroachlabs.github.io/cockroachdb-python-library/simple/ + +cockroachdb==0.1.2 +psycopg[binary]>=3.1 +pytest>=8.0 +testcontainers>=4.0 # integration test only; boots CockroachDB in --insecure mode diff --git a/examples/ideas-board/service.py b/examples/ideas-board/service.py new file mode 100644 index 0000000..1409a6e --- /dev/null +++ b/examples/ideas-board/service.py @@ -0,0 +1,64 @@ +"""Upvote service: the plain path loses votes, the @crdb_retry path lands them all. + +Both functions perform the SAME read-modify-write against a single hot row +under SERIALIZABLE isolation, so CockroachDB raises a serialization conflict +(SQLSTATE 40001) when concurrent upvotes collide. The only difference is the +decorator. +""" + +from __future__ import annotations + +import time + +import psycopg + +import repository + +# tag::retry[] +from cockroachdb import IsolationLevel, crdb_retry + +# end::retry[] + +# Pause between the read and the write to widen the conflict window so +# concurrent upvotes reliably collide. ponytail: fixed delay, tune per cluster. +CONTENTION_DELAY = 0.05 + + +def _apply_upvote(dsn: str, idea_id: int) -> None: + """Read current votes, add one, write it back — in one SERIALIZABLE tx. + + Opens its OWN connection every call. @crdb_retry re-executes the whole + decorated function on a 40001, and CockroachDB's retry protocol requires + a brand-new transaction each attempt, so the connection must be created + inside the retried unit — not passed in. + """ + with psycopg.connect(dsn, autocommit=True) as conn: + conn.execute( + "SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL SERIALIZABLE" + ) + with conn.transaction(), conn.cursor() as cur: + votes = repository.current_votes(cur, idea_id) + time.sleep(CONTENTION_DELAY) + repository.update_votes(cur, idea_id, votes + 1) + + +# tag::plain[] +def upvote_without_retry(dsn: str, idea_id: int) -> None: + """Upvote with NO retry — a 40001 propagates and that vote is lost.""" + with psycopg.connect(dsn, autocommit=True) as conn: + conn.execute( + "SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL SERIALIZABLE" + ) + with conn.transaction(), conn.cursor() as cur: + votes = repository.current_votes(cur, idea_id) # <1> + new_votes = votes + 1 # <2> + repository.update_votes(cur, idea_id, new_votes) # <3> +# end::plain[] + + +# tag::retry[] +@crdb_retry(max_retries=25, base_delay=0.02, isolation=IsolationLevel.SERIALIZABLE) # <1> +def upvote(dsn: str, idea_id: int) -> None: + """Upvote WITH automatic retry — every vote eventually lands.""" + _apply_upvote(dsn, idea_id) +# end::retry[] diff --git a/examples/ideas-board/test_concurrency.py b/examples/ideas-board/test_concurrency.py new file mode 100644 index 0000000..eca0486 --- /dev/null +++ b/examples/ideas-board/test_concurrency.py @@ -0,0 +1,83 @@ +"""Integration test — spins up a real CockroachDB via testcontainers. + +3 threads x 20 upvotes = 60 total. A per-round barrier forces all three +threads to collide on the same row, so: + - the plain path loses votes to 40001 (never reaches 60) + - the @crdb_retry path lands every vote (exactly 60) + +Skips cleanly when Docker / testcontainers is unavailable. +""" + +from __future__ import annotations + +import threading + +import pytest + +import repository +import service + +THREADS = 3 +PER_THREAD = 20 +TOTAL = THREADS * PER_THREAD + + +@pytest.fixture(scope="module") +def dsn() -> str: + try: + from crdb_container import insecure_crdb + except Exception as exc: # noqa: BLE001 + pytest.skip(f"testcontainers unavailable: {exc}") + + try: + with insecure_crdb() as url: + yield url + except Exception as exc: # noqa: BLE001 — Docker not running / image pull failed + pytest.skip(f"Docker/CockroachDB container unavailable: {exc}") + + +def _seed(dsn: str) -> int: + import psycopg + + with psycopg.connect(dsn, autocommit=True) as conn, conn.cursor() as cur: + repository.create_schema(cur) + return repository.seed(cur, "Concurrent upvote stress test") + + +def _votes(dsn: str, idea_id: int) -> int: + import psycopg + + with psycopg.connect(dsn, autocommit=True) as conn, conn.cursor() as cur: + return repository.current_votes(cur, idea_id) + + +def _run(dsn: str, idea_id: int, fn) -> None: + """3 threads x 20 rounds; a barrier makes all 3 collide each round.""" + barrier = threading.Barrier(THREADS) + + def worker() -> None: + for _ in range(PER_THREAD): + barrier.wait() + try: + fn(dsn, idea_id) + except Exception: # noqa: BLE001 — plain path drops conflicts + pass + + threads = [threading.Thread(target=worker) for _ in range(THREADS)] + for t in threads: + t.start() + for t in threads: + t.join() + + +# tag::concurrency-test[] +def test_retry_lands_every_vote(dsn: str) -> None: + idea_id = _seed(dsn) + + _run(dsn, idea_id, service.upvote) + assert _votes(dsn, idea_id) == TOTAL # retry path: all 60 land + + plain_id = _seed(dsn) + _run(dsn, plain_id, service.upvote_without_retry) + assert _votes(dsn, plain_id) < TOTAL # plain path: conflicts lose votes +# end::concurrency-test[] diff --git a/examples/ideas-board/test_unit.py b/examples/ideas-board/test_unit.py new file mode 100644 index 0000000..94e8973 --- /dev/null +++ b/examples/ideas-board/test_unit.py @@ -0,0 +1,69 @@ +"""Fast unit test — no Docker, no database. + +Mocks psycopg so the whole read-modify-write runs in memory, proving +`upvote_without_retry` reads the current vote count and writes count + 1. +""" + +from __future__ import annotations + +import contextlib + +import pytest + +import service + + +class _FakeCursor: + def __init__(self, store: dict) -> None: + self._store = store + + def __enter__(self) -> _FakeCursor: + return self + + def __exit__(self, *exc) -> None: + return None + + def execute(self, sql: str, params: tuple | None = None) -> None: + self._store.setdefault("executed", []).append((sql, params)) + if sql.strip().upper().startswith("UPDATE"): + # params = (new_votes, idea_id) + self._store["written"] = params[0] + + def fetchone(self) -> tuple: + return (self._store["votes"],) + + +class _FakeConnection: + def __init__(self, store: dict) -> None: + self._store = store + + def __enter__(self) -> _FakeConnection: + return self + + def __exit__(self, *exc) -> None: + return None + + def execute(self, sql: str, params: tuple | None = None) -> None: + pass # SET SESSION CHARACTERISTICS — nothing to simulate + + @contextlib.contextmanager + def transaction(self): + yield self + + def cursor(self) -> _FakeCursor: + return _FakeCursor(self._store) + + +# tag::unit-test[] +def test_upvote_without_retry_reads_then_writes_plus_one(monkeypatch: pytest.MonkeyPatch) -> None: + store = {"votes": 41} + + def fake_connect(dsn: str, autocommit: bool = False) -> _FakeConnection: + return _FakeConnection(store) + + monkeypatch.setattr(service.psycopg, "connect", fake_connect) + + service.upvote_without_retry("postgresql://ignored", idea_id=7) + + assert store["written"] == 42 # read 41, wrote 41 + 1 +# end::unit-test[] From 2918cee273bd5aed30418e5c462706b5513f3c4b Mon Sep 17 00:00:00 2001 From: Felipe Gutierrez Date: Thu, 19 Nov 2026 09:00:41 -0500 Subject: [PATCH 2/4] ideas-board: drop tutorial callout markers (tutorial uses si window callouts) --- examples/ideas-board/service.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/examples/ideas-board/service.py b/examples/ideas-board/service.py index 1409a6e..ca9c040 100644 --- a/examples/ideas-board/service.py +++ b/examples/ideas-board/service.py @@ -50,14 +50,14 @@ def upvote_without_retry(dsn: str, idea_id: int) -> None: "SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL SERIALIZABLE" ) with conn.transaction(), conn.cursor() as cur: - votes = repository.current_votes(cur, idea_id) # <1> - new_votes = votes + 1 # <2> - repository.update_votes(cur, idea_id, new_votes) # <3> + votes = repository.current_votes(cur, idea_id) + new_votes = votes + 1 + repository.update_votes(cur, idea_id, new_votes) # end::plain[] # tag::retry[] -@crdb_retry(max_retries=25, base_delay=0.02, isolation=IsolationLevel.SERIALIZABLE) # <1> +@crdb_retry(max_retries=25, base_delay=0.02, isolation=IsolationLevel.SERIALIZABLE) def upvote(dsn: str, idea_id: int) -> None: """Upvote WITH automatic retry — every vote eventually lands.""" _apply_upvote(dsn, idea_id) From 6be390f9e9b02480bfa2e6467cb6a35872728bbc Mon Sep 17 00:00:00 2001 From: Felipe Gutierrez Date: Thu, 19 Nov 2026 11:26:36 -0500 Subject: [PATCH 3/4] Add 5 feature demos to Python ideas-board example Mirror the Java demo's metrics, follower-read, CDC, multi-region, and semantic-search features in Python idiom against this library's real API: - metrics: RetryEngine + InMemoryMetricsCollector count transactions/retries - follower-read: @follower_read + build_staleness, cooperative AS OF SYSTEM TIME - cdc: @changefeed_handler + ChangefeedHandlerRegistry webhook dispatch - multi-region: @regional_by_row + RegionContext, explicit crdb_region write - semantic-search: CockroachDBVectorStore + deterministic embedding provider Each feature ships a runnable unit test plus a Testcontainers integration test; multi-region and semantic ITs are gated (multi-region cluster / vector image). Tagged regions added for tutorial include. --- examples/ideas-board/cdc_handler.py | 46 ++++++++++ examples/ideas-board/crdb_container.py | 10 ++- examples/ideas-board/follower_read_service.py | 57 ++++++++++++ examples/ideas-board/metrics_service.py | 70 +++++++++++++++ examples/ideas-board/regional_service.py | 87 +++++++++++++++++++ examples/ideas-board/requirements.txt | 5 +- examples/ideas-board/semantic_service.py | 86 ++++++++++++++++++ examples/ideas-board/test_cdc.py | 59 +++++++++++++ examples/ideas-board/test_follower_read.py | 45 ++++++++++ examples/ideas-board/test_follower_read_it.py | 65 ++++++++++++++ examples/ideas-board/test_metrics.py | 41 +++++++++ examples/ideas-board/test_metrics_it.py | 63 ++++++++++++++ examples/ideas-board/test_regional.py | 39 +++++++++ examples/ideas-board/test_regional_it.py | 41 +++++++++ examples/ideas-board/test_semantic.py | 38 ++++++++ examples/ideas-board/test_semantic_it.py | 70 +++++++++++++++ 16 files changed, 818 insertions(+), 4 deletions(-) create mode 100644 examples/ideas-board/cdc_handler.py create mode 100644 examples/ideas-board/follower_read_service.py create mode 100644 examples/ideas-board/metrics_service.py create mode 100644 examples/ideas-board/regional_service.py create mode 100644 examples/ideas-board/semantic_service.py create mode 100644 examples/ideas-board/test_cdc.py create mode 100644 examples/ideas-board/test_follower_read.py create mode 100644 examples/ideas-board/test_follower_read_it.py create mode 100644 examples/ideas-board/test_metrics.py create mode 100644 examples/ideas-board/test_metrics_it.py create mode 100644 examples/ideas-board/test_regional.py create mode 100644 examples/ideas-board/test_regional_it.py create mode 100644 examples/ideas-board/test_semantic.py create mode 100644 examples/ideas-board/test_semantic_it.py diff --git a/examples/ideas-board/cdc_handler.py b/examples/ideas-board/cdc_handler.py new file mode 100644 index 0000000..d10fdcd --- /dev/null +++ b/examples/ideas-board/cdc_handler.py @@ -0,0 +1,46 @@ +"""CDC: a changefeed webhook handler for the ideas table. + +The ``@changefeed_handler`` decorator tags a function with table/operations/endpoint +metadata; ``ChangefeedHandlerRegistry`` parses an incoming webhook envelope into +``ChangefeedEvent``s and dispatches each to the handler. Insert/update events are +projected onto an ``Idea``; deletes (after-image is ``None``) are counted. + +This mirrors the Java ``IdeaChangefeedHandler``: it is pure event-processing logic, +so it is fully exercised without a live changefeed (see ``test_cdc.py``). A real +webhook-sink changefeed is created with ``ChangefeedManager`` against a live +cluster; that path needs an enterprise license + a reachable sink, so — like the +Java demo — there is no CDC integration test here. +""" + +from __future__ import annotations + +from typing import Any + +from idea import Idea + +# tag::cdc-handler[] +from cockroachdb import changefeed_handler + + +class IdeaChangefeedHandler: + """Turns ``idea`` changefeed events into ``Idea``s and tracks deletes.""" + + TABLE = "ideas" + + def __init__(self) -> None: + self.handled: list[Idea] = [] + self.deletes = 0 + + @changefeed_handler(table=TABLE, operations=["insert", "update", "delete"]) + def on_change(self, event: Any) -> None: + """Project an insert/update ``after`` image onto an ``Idea``; count deletes.""" + if event.after is None: # delete: no after-image + self.deletes += 1 + return + after = event.after + self.handled.append( + Idea(id=after["id"], text=after["text"], votes=after["votes"]) + ) + + +# end::cdc-handler[] diff --git a/examples/ideas-board/crdb_container.py b/examples/ideas-board/crdb_container.py index fe89875..ad2be47 100644 --- a/examples/ideas-board/crdb_container.py +++ b/examples/ideas-board/crdb_container.py @@ -21,13 +21,17 @@ @contextlib.contextmanager -def insecure_crdb() -> Iterator[str]: - """Start an insecure single-node CockroachDB; yield a psycopg DSN.""" +def insecure_crdb(image: str = IMAGE) -> Iterator[str]: + """Start an insecure single-node CockroachDB; yield a psycopg DSN. + + ``image`` defaults to the pinned fundamentals image; the semantic-search IT + overrides it with a VECTOR-capable image (v25.2+). + """ from testcontainers.core.container import DockerContainer from testcontainers.core.waiting_utils import wait_for_logs container = ( - DockerContainer(IMAGE) + DockerContainer(image) .with_command("start-single-node --insecure") .with_exposed_ports(26257) ) diff --git a/examples/ideas-board/follower_read_service.py b/examples/ideas-board/follower_read_service.py new file mode 100644 index 0000000..ec0d920 --- /dev/null +++ b/examples/ideas-board/follower_read_service.py @@ -0,0 +1,57 @@ +"""Follower-read leaderboard: read the top ideas AS OF SYSTEM TIME so the query +is served by the nearest replica instead of the leaseholder. + +The library's ``build_staleness()`` helper and the ``@follower_read`` decorator +supply the AS OF SYSTEM TIME expression; ``FollowerReadContext`` carries it across +a call. NOTE: the plain-psycopg ``CockroachDBTemplate`` does NOT auto-inject +AS OF SYSTEM TIME (only the SQLAlchemy layer does), so this service applies the +resolved staleness to the SELECT itself — the cooperative pattern for a +psycopg app, exactly how the Java demo threads its staleness through. +""" + +from __future__ import annotations + +import psycopg + +from idea import Idea + +# tag::follower-read[] +from cockroachdb import build_staleness, follower_read +from cockroachdb.core import FollowerReadContext + + +@follower_read("follower_read_timestamp()") +def top_ideas(dsn: str, limit: int = 10) -> list[Idea]: + """Top ideas by votes, read from a follower snapshot. + + ``@follower_read`` stamps the resolved staleness on this function + (``__crdb_follower_read__``); we read it back and apply it. The staleness is + library-controlled (a builtin like ``follower_read_timestamp()`` or an + interval like ``'-5s'``), never user input, so it is safe to interpolate. + """ + staleness = getattr(top_ideas, "__crdb_follower_read__", build_staleness()) + sql = ( + "SELECT id, text, votes FROM ideas " + f"AS OF SYSTEM TIME {staleness} " + "ORDER BY votes DESC, text ASC LIMIT %s" + ) + with psycopg.connect(dsn, autocommit=True) as conn, conn.cursor() as cur: + cur.execute(sql, (limit,)) + return [Idea(id=r[0], text=r[1], votes=r[2]) for r in cur.fetchall()] + + +def top_ideas_scoped(dsn: str, limit: int, *, seconds_ago: int) -> list[Idea]: + """Same read, but the staleness comes from a ``FollowerReadContext`` block — + the signal a middleware or template layer would set for the whole request.""" + with FollowerReadContext.scoped(seconds_ago=seconds_ago) as staleness: + sql = ( + "SELECT id, text, votes FROM ideas " + f"AS OF SYSTEM TIME {staleness} " + "ORDER BY votes DESC, text ASC LIMIT %s" + ) + with psycopg.connect(dsn, autocommit=True) as conn, conn.cursor() as cur: + cur.execute(sql, (limit,)) + return [Idea(id=r[0], text=r[1], votes=r[2]) for r in cur.fetchall()] + + +# end::follower-read[] diff --git a/examples/ideas-board/metrics_service.py b/examples/ideas-board/metrics_service.py new file mode 100644 index 0000000..972aec0 --- /dev/null +++ b/examples/ideas-board/metrics_service.py @@ -0,0 +1,70 @@ +"""Metered upvotes: run each read-modify-write through the core RetryEngine so +retry and transaction counters move under contention. + +Fundamentals (``service.py``) proves ``@crdb_retry`` lands every vote. This layers +the library's metrics on top: ``RetryEngine`` records one transaction per run +(COMMITTED or RETRIED) and one retry per serialization conflict (40001) into any +``MetricsCollector`` — here the ``InMemoryMetricsCollector`` you can inspect. +""" + +from __future__ import annotations + +import time +from typing import TYPE_CHECKING + +import psycopg + +import repository + +# tag::metrics-config[] +from cockroachdb.core import RetryEngine +from cockroachdb.core.metrics import InMemoryMetricsCollector +from cockroachdb.types import RetryPolicy + +# end::metrics-config[] + +if TYPE_CHECKING: + from cockroachdb.types import MetricsCollector + +# Pause between read and write to widen the conflict window. Same knob as the +# fundamentals demo. ponytail: fixed delay, tune per cluster. +CONTENTION_DELAY = 0.05 + + +class MeteredIdeaService: + """Upvotes wrapped in ``RetryEngine.run`` so every attempt is counted.""" + + def __init__( + self, + dsn: str, + metrics: MetricsCollector | None = None, + *, + max_retries: int = 25, + ) -> None: + self._dsn = dsn + self.metrics = metrics or InMemoryMetricsCollector() + # tag::metrics-engine[] + self._engine = RetryEngine( + policy=RetryPolicy(max_retries=max_retries, base_delay=0.02), + metrics=self.metrics, + ) + # end::metrics-engine[] + + # tag::metered-upvote[] + def upvote(self, idea_id: int) -> None: + """One metered upvote. ``RetryEngine.run`` records the transaction outcome + and any 40001 retries into the attached metrics collector.""" + self._engine.run(lambda: self._apply_upvote(idea_id)) + + # end::metered-upvote[] + + def _apply_upvote(self, idea_id: int) -> None: + """Read current votes, add one, write it back — in one SERIALIZABLE tx.""" + with psycopg.connect(self._dsn, autocommit=True) as conn: + conn.execute( + "SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL SERIALIZABLE" + ) + with conn.transaction(), conn.cursor() as cur: + votes = repository.current_votes(cur, idea_id) + time.sleep(CONTENTION_DELAY) + repository.update_votes(cur, idea_id, votes + 1) diff --git a/examples/ideas-board/regional_service.py b/examples/ideas-board/regional_service.py new file mode 100644 index 0000000..e42379f --- /dev/null +++ b/examples/ideas-board/regional_service.py @@ -0,0 +1,87 @@ +"""Multi-region: REGIONAL BY ROW writes that home each idea in a chosen region. + +``@regional_by_row`` marks the entity; ``@crdb_region`` pins a function to a region; +``RegionContext.scoped(region)`` carries the region across a call; the write sets +the hidden ``crdb_region`` column from that context. + +NOTE: like follower reads, the psycopg path is cooperative — only the SQLAlchemy +layer auto-issues ``SET crdb_region``, so this service writes ``crdb_region`` +explicitly. That is exactly what the Java demo does too (it sets ``crdb_region`` +from its call context rather than relying on the gateway region). + +REGIONAL BY ROW requires a multi-region database (multiple ADD REGIONs), which a +single node does not have, so the integration test is gated and skips by default. +""" + +from __future__ import annotations + +from dataclasses import dataclass + +import psycopg + +# tag::regional-entity[] +from cockroachdb import crdb_region, regional_by_row +from cockroachdb.core import RegionContext + + +@regional_by_row(default_region="us-east1") +@dataclass +class RegionalIdea: + """An idea pinned to a region via the hidden ``crdb_region`` column.""" + + id: str + text: str + region: str + + +# end::regional-entity[] + + +# tag::region-config[] +# Enablement DDL. On a multi-region database (ALTER DATABASE ... ADD REGION ...) +# this makes the table REGIONAL BY ROW, adding the hidden crdb_region column. +REGIONAL_BY_ROW_DDL = ( + "CREATE TABLE IF NOT EXISTS regional_idea " + "(id UUID PRIMARY KEY DEFAULT gen_random_uuid(), text STRING NOT NULL);" + "ALTER TABLE regional_idea SET LOCALITY REGIONAL BY ROW" +) +# end::region-config[] + + +# tag::inregion-usage[] +def add_in_region(dsn: str, region: str, text: str) -> str: + """Store an idea homed in ``region`` by writing ``crdb_region`` from the context.""" + RegionContext.validate(region) + with RegionContext.scoped(region): + bound = RegionContext.current() + with psycopg.connect(dsn, autocommit=True) as conn, conn.cursor() as cur: + cur.execute( + "INSERT INTO regional_idea (text, crdb_region) VALUES (%s, %s) RETURNING id", + (text, bound), + ) + return str(cur.fetchone()[0]) + + +@crdb_region("us-east1") +def add_in_us_east(dsn: str, text: str) -> str: + """Store an idea homed in us-east1 (region read back from ``@crdb_region``).""" + return add_in_region(dsn, add_in_us_east.__crdb_region__, text) + + +@crdb_region("us-west1") +def add_in_us_west(dsn: str, text: str) -> str: + """Store an idea homed in us-west1.""" + return add_in_region(dsn, add_in_us_west.__crdb_region__, text) + + +def region_of(dsn: str, idea_id: str) -> str | None: + """The ``crdb_region`` a row actually landed in, if present.""" + with psycopg.connect(dsn, autocommit=True) as conn, conn.cursor() as cur: + cur.execute( + "SELECT crdb_region::STRING FROM regional_idea WHERE id = %s", (idea_id,) + ) + row = cur.fetchone() + return row[0] if row else None + + +# end::inregion-usage[] diff --git a/examples/ideas-board/requirements.txt b/examples/ideas-board/requirements.txt index e08e4dd..1bb9c8a 100644 --- a/examples/ideas-board/requirements.txt +++ b/examples/ideas-board/requirements.txt @@ -5,6 +5,9 @@ --extra-index-url https://cockroachlabs.github.io/cockroachdb-python-library/simple/ cockroachdb==0.1.2 +cockroachdb-core==0.1.2 # metrics (RetryEngine) + follower-read/region context +cockroachdb-cdc==0.1.1 # changefeed handlers + webhook payload parsing +cockroachdb-ai==0.1.1 # pgvector vector store (semantic search); IT needs cockroach >= v25.2 psycopg[binary]>=3.1 pytest>=8.0 -testcontainers>=4.0 # integration test only; boots CockroachDB in --insecure mode +testcontainers>=4.0 # integration tests only; boot CockroachDB in --insecure mode diff --git a/examples/ideas-board/semantic_service.py b/examples/ideas-board/semantic_service.py new file mode 100644 index 0000000..8b4184e --- /dev/null +++ b/examples/ideas-board/semantic_service.py @@ -0,0 +1,86 @@ +"""Semantic search over ideas using the AI module's ``CockroachDBVectorStore`` on a +native ``VECTOR`` column. + +A deterministic (no-model) embedding provider keeps the demo reproducible — a real +app swaps in ``OpenAIEmbeddingProvider`` or ``SentenceTransformerEmbeddingProvider``. +Ideas are stored with precomputed embeddings; the query is embedded through the same +provider, and ``similarity_search`` returns the nearest ideas by cosine distance. + +Needs CockroachDB with the native ``VECTOR`` type (v25.2+). ``ensure_table()`` also +issues ``CREATE VECTOR INDEX`` (v26.2+); the integration test skips honestly when +the image lacks VECTOR support. +""" + +from __future__ import annotations + +import hashlib +from typing import TYPE_CHECKING + +from cockroachdb.ai import CockroachDBVectorStore, Document +from cockroachdb.config import AIConfig + +if TYPE_CHECKING: + from cockroachdb.types import VectorSearchResult + +DIMENSIONS = 3 +TABLE = "idea_doc" + + +# tag::embedding-provider[] +class DeterministicEmbeddingProvider: + """A no-model EmbeddingProvider: fixed text->vector mapping with a hash fallback. + + Satisfies the ``EmbeddingProvider`` protocol (``embed`` / ``embed_batch`` / + ``dimensions``) so searches are reproducible with no external model or network. + """ + + def __init__( + self, mapping: dict[str, list[float]], dimensions: int = DIMENSIONS + ) -> None: + self._mapping = mapping + self._dimensions = dimensions + + @property + def dimensions(self) -> int: + return self._dimensions + + async def embed(self, text: str) -> list[float]: + if text in self._mapping: + return self._mapping[text] + digest = hashlib.sha256(text.encode()).digest() + return [digest[i] / 255.0 for i in range(self._dimensions)] + + async def embed_batch(self, texts: list[str]) -> list[list[float]]: + return [await self.embed(t) for t in texts] + + +# end::embedding-provider[] + + +# tag::vector-search[] +class SemanticIdeaService: + """Store ideas with precomputed embeddings; find the nearest by cosine distance.""" + + def __init__(self, dsn: str, provider: DeterministicEmbeddingProvider) -> None: + self._store = CockroachDBVectorStore( + conninfo=dsn, + table=TABLE, + vector_column="embedding", + embedding_provider=provider, + config=AIConfig(embedding_dimensions=DIMENSIONS, default_metric="cosine"), + ) + + def initialize(self) -> None: + """Create the VECTOR table (and index). Safe to call repeatedly.""" + self._store.ensure_table() + + async def store(self, docs: list[Document]) -> list[str]: + """Upsert ideas carrying precomputed embeddings.""" + return await self._store.add_documents(docs) + + async def find_similar(self, query: str, k: int = 4) -> list[VectorSearchResult]: + """The ``k`` ideas nearest to ``query``, closest-first.""" + return await self._store.similarity_search(query, limit=k) + + +# end::vector-search[] diff --git a/examples/ideas-board/test_cdc.py b/examples/ideas-board/test_cdc.py new file mode 100644 index 0000000..931b2fa --- /dev/null +++ b/examples/ideas-board/test_cdc.py @@ -0,0 +1,59 @@ +"""Fast unit test for CDC — no Docker, no changefeed. + +CDC processing is pure logic: classify the event from before/after presence, and +project the ``after`` image onto an ``Idea``. The library ships a real parser and +registry, so we exercise two paths: ``ChangefeedPayload.parse`` directly on a +wrapped webhook envelope, and the full ``ChangefeedHandlerRegistry.dispatch`` +decode-and-dispatch to the decorated handler (mirrors the Java CDC unit test). +""" + +from __future__ import annotations + +import asyncio + +from cdc_handler import IdeaChangefeedHandler +from cockroachdb.cdc import ( + ChangefeedHandlerRegistry, + ChangefeedPayload, + InMemoryCDCMetrics, +) +from cockroachdb.types import CDCOperation + + +# tag::cdc-unit-test[] +def test_parse_envelope_classifies_insert_and_delete() -> None: + envelope = ( + '{"payload":[' + '{"after":{"id":1,"text":"Dark mode","votes":7},"key":[1],' + '"topic":"ideas","updated":"1700000000.0"},' + '{"after":null,"before":{"id":1,"text":"Dark mode","votes":7},"key":[1],' + '"topic":"ideas","updated":"1700000001.0"}' + '],"length":2}' + ) + events = ChangefeedPayload.parse(envelope).events + assert [e.operation for e in events] == [CDCOperation.INSERT, CDCOperation.DELETE] + + +def test_registry_dispatches_webhook_to_handler() -> None: + handler = IdeaChangefeedHandler() + metrics = InMemoryCDCMetrics() + registry = ChangefeedHandlerRegistry(metrics=metrics) + registry.register(handler.on_change) + + envelope = ( + '{"payload":[' + '{"after":{"id":12,"text":"Full-text search","votes":12},"key":[12],' + '"topic":"ideas","updated":"1700000002.0"}' + '],"length":1}' + ) + results = asyncio.run(registry.dispatch("/webhooks/ideas", envelope)) + + assert len(results) == 1 + assert len(handler.handled) == 1 + seen = handler.handled[0] + assert seen.id == 12 + assert seen.text == "Full-text search" + assert seen.votes == 12 + assert handler.deletes == 0 + assert metrics.total_events == 1 +# end::cdc-unit-test[] diff --git a/examples/ideas-board/test_follower_read.py b/examples/ideas-board/test_follower_read.py new file mode 100644 index 0000000..3806919 --- /dev/null +++ b/examples/ideas-board/test_follower_read.py @@ -0,0 +1,45 @@ +"""Fast unit test for follower reads — no Docker, no database. + +Covers the genuinely unit-testable logic: staleness composition via +``build_staleness``, the ``@follower_read`` decorator's stamped expression, the +fail-fast on a negative part, and the ``FollowerReadContext`` scope. The real +follower-snapshot read needs a cluster (see ``test_follower_read_it.py``). +""" + +from __future__ import annotations + +import pytest + +import follower_read_service as frs +from cockroachdb import build_staleness, follower_read +from cockroachdb.core import FollowerReadContext + + +# tag::follower-read-unit-test[] +def test_build_staleness_defaults_and_additive() -> None: + assert build_staleness() == "follower_read_timestamp()" + assert build_staleness(seconds_ago=5) == "'-5s'" + assert build_staleness(minutes_ago=1, seconds_ago=30) == "'-90s'" + + +def test_follower_read_decorator_stamps_resolved_staleness() -> None: + assert frs.top_ideas.__crdb_follower_read__ == "follower_read_timestamp()" + + @follower_read(seconds_ago=10) + def reader() -> None: ... + + assert reader.__crdb_follower_read__ == "'-10s'" + + +def test_negative_staleness_fails_fast() -> None: + with pytest.raises(ValueError): + build_staleness(seconds_ago=-1) + + +def test_scoped_context_activates_and_resets() -> None: + assert FollowerReadContext.current_staleness() is None + with FollowerReadContext.scoped(seconds_ago=5) as staleness: + assert staleness == "'-5s'" + assert FollowerReadContext.is_active() + assert FollowerReadContext.current_staleness() is None +# end::follower-read-unit-test[] diff --git a/examples/ideas-board/test_follower_read_it.py b/examples/ideas-board/test_follower_read_it.py new file mode 100644 index 0000000..a5e8383 --- /dev/null +++ b/examples/ideas-board/test_follower_read_it.py @@ -0,0 +1,65 @@ +"""Integration test for follower reads — real CockroachDB via testcontainers. + +Seeds three ideas, then reads the leaderboard AS OF SYSTEM TIME +``follower_read_timestamp()`` (~4.8s stale). Because the read is historical, +freshly-seeded rows are invisible until the staleness window advances, so the +test polls until the snapshot catches up (mirrors the Java follower-read IT). + +Skips cleanly when Docker / testcontainers is unavailable. +""" + +from __future__ import annotations + +import time + +import psycopg +import pytest + +import repository +from follower_read_service import top_ideas + + +@pytest.fixture(scope="module") +def dsn() -> str: + try: + from crdb_container import insecure_crdb + except Exception as exc: # noqa: BLE001 + pytest.skip(f"testcontainers unavailable: {exc}") + try: + with insecure_crdb() as url: + yield url + except Exception as exc: # noqa: BLE001 — Docker not running / image pull failed + pytest.skip(f"Docker/CockroachDB container unavailable: {exc}") + + +def _insert(dsn: str, text: str, votes: int) -> None: + with psycopg.connect(dsn, autocommit=True) as conn, conn.cursor() as cur: + cur.execute("INSERT INTO ideas (text, votes) VALUES (%s, %s)", (text, votes)) + + +# tag::follower-read-it[] +def test_top_ideas_from_follower_snapshot(dsn: str) -> None: + with psycopg.connect(dsn, autocommit=True) as conn, conn.cursor() as cur: + repository.create_schema(cur) + _insert(dsn, "Dark mode", 5) + _insert(dsn, "Full-text search", 12) + _insert(dsn, "CSV export", 3) + + # follower_read_timestamp() is ~4.8s stale; poll until the snapshot advances + # past the freshly-inserted rows. + deadline = time.monotonic() + 30 + top: list = [] + while time.monotonic() < deadline: + try: + top = top_ideas(dsn, 10) + except psycopg.Error: + pass # as-of-time read predates the schema; retry as the window advances + if len(top) >= 3: + break + time.sleep(0.5) + + assert len(top) == 3 + assert top[0].text == "Full-text search" # highest votes sorts first + assert top[0].votes == 12 + assert [i.votes for i in top] == sorted((i.votes for i in top), reverse=True) +# end::follower-read-it[] diff --git a/examples/ideas-board/test_metrics.py b/examples/ideas-board/test_metrics.py new file mode 100644 index 0000000..ecbfe0a --- /dev/null +++ b/examples/ideas-board/test_metrics.py @@ -0,0 +1,41 @@ +"""Fast unit test for metered upvotes — no Docker, no database. + +Simulates a serialization conflict (SQLSTATE 40001) so the REAL ``RetryEngine`` + +``InMemoryMetricsCollector`` count a retry and a RETRIED transaction. The library +classifies retryability off an exception's ``sqlstate``/``pgcode`` (walking the +cause chain), so a stand-in exception with ``sqlstate = "40001"`` exercises the +exact production path without psycopg or a cluster. +""" + +from __future__ import annotations + +from cockroachdb.core import RetryEngine +from cockroachdb.core.metrics import InMemoryMetricsCollector +from cockroachdb.types import RetryPolicy, TransactionOutcome + + +class _Fake40001(Exception): + """Stand-in for psycopg's SerializationFailure (SQLSTATE 40001).""" + + sqlstate = "40001" + + +# tag::metrics-unit-test[] +def test_retry_engine_counts_retries_and_outcome() -> None: + metrics = InMemoryMetricsCollector() + engine = RetryEngine(RetryPolicy(max_retries=5, base_delay=0.0), metrics=metrics) + + calls = {"n": 0} + + def flaky() -> str: + calls["n"] += 1 + if calls["n"] < 3: + raise _Fake40001("restart transaction") # retryable + return "ok" + + assert engine.run(flaky) == "ok" + assert calls["n"] == 3 + assert metrics.total_retries == 2 # two 40001s absorbed + assert metrics.transactions[TransactionOutcome.RETRIED] # retried run recorded + assert metrics.total_transactions == 1 # one logical transaction +# end::metrics-unit-test[] diff --git a/examples/ideas-board/test_metrics_it.py b/examples/ideas-board/test_metrics_it.py new file mode 100644 index 0000000..a3964c6 --- /dev/null +++ b/examples/ideas-board/test_metrics_it.py @@ -0,0 +1,63 @@ +"""Integration test for metrics — spins up a real CockroachDB via testcontainers. + +4 workers x 10 upvotes = 40 total on one hot row. A per-round barrier forces +collisions, so the metered path records exactly 40 transactions and a non-zero +retry count (real 40001s absorbed by the engine). + +Skips cleanly when Docker / testcontainers is unavailable. +""" + +from __future__ import annotations + +import threading + +import psycopg +import pytest + +import repository +from metrics_service import MeteredIdeaService + +WORKERS = 4 +ITERATIONS = 10 +EXPECTED = WORKERS * ITERATIONS + + +@pytest.fixture(scope="module") +def dsn() -> str: + try: + from crdb_container import insecure_crdb + except Exception as exc: # noqa: BLE001 + pytest.skip(f"testcontainers unavailable: {exc}") + try: + with insecure_crdb() as url: + yield url + except Exception as exc: # noqa: BLE001 — Docker not running / image pull failed + pytest.skip(f"Docker/CockroachDB container unavailable: {exc}") + + +# tag::metrics-it[] +def test_metrics_count_transactions_and_retries(dsn: str) -> None: + with psycopg.connect(dsn, autocommit=True) as conn, conn.cursor() as cur: + repository.create_schema(cur) + idea_id = repository.seed(cur, "Instrument the ideas board") + + service = MeteredIdeaService(dsn) + barrier = threading.Barrier(WORKERS) + + def worker() -> None: + for _ in range(ITERATIONS): + barrier.wait() + service.upvote(idea_id) + + threads = [threading.Thread(target=worker) for _ in range(WORKERS)] + for t in threads: + t.start() + for t in threads: + t.join() + + with psycopg.connect(dsn, autocommit=True) as conn, conn.cursor() as cur: + assert repository.current_votes(cur, idea_id) == EXPECTED # retry absorbs conflicts + + assert service.metrics.total_transactions == EXPECTED # one per metered upvote + assert service.metrics.total_retries > 0 # contention forces 40001 retries +# end::metrics-it[] diff --git a/examples/ideas-board/test_regional.py b/examples/ideas-board/test_regional.py new file mode 100644 index 0000000..8ec5692 --- /dev/null +++ b/examples/ideas-board/test_regional.py @@ -0,0 +1,39 @@ +"""Fast unit test for multi-region — no Docker, no database. + +Covers the decorator metadata (``@regional_by_row``, ``@crdb_region``), the +``RegionContext`` scope, and region-name validation. The REGIONAL BY ROW writes +need a multi-region cluster and are gated in ``test_regional_it.py``. +""" + +from __future__ import annotations + +import pytest + +import regional_service as rs +from cockroachdb.core import RegionContext +from cockroachdb.exceptions import RegionValidationError + + +# tag::regional-unit-test[] +def test_regional_by_row_marks_entity() -> None: + assert rs.RegionalIdea.__crdb_regional_by_row__ is True + assert rs.RegionalIdea.__crdb_default_region__ == "us-east1" + + +def test_crdb_region_decorator_pins_region() -> None: + assert rs.add_in_us_east.__crdb_region__ == "us-east1" + assert rs.add_in_us_west.__crdb_region__ == "us-west1" + + +def test_region_context_scopes_and_resets() -> None: + assert RegionContext.current() is None + with RegionContext.scoped("us-west1"): + assert RegionContext.current() == "us-west1" + assert RegionContext.current() is None + + +def test_region_validation_rejects_bad_names() -> None: + RegionContext.validate("us-east1") # valid — no raise + with pytest.raises(RegionValidationError): + RegionContext.validate("US_EAST!") +# end::regional-unit-test[] diff --git a/examples/ideas-board/test_regional_it.py b/examples/ideas-board/test_regional_it.py new file mode 100644 index 0000000..3b31c35 --- /dev/null +++ b/examples/ideas-board/test_regional_it.py @@ -0,0 +1,41 @@ +"""Integration test for REGIONAL BY ROW — gated on a real multi-region cluster. + +REGIONAL BY ROW needs a database with multiple regions (e.g. us-east1 + us-west1 +added via ALTER DATABASE ... ADD REGION), which a single Testcontainers node does +not have. This test therefore SKIPS unless ``CRDB_MULTIREGION=true``; when enabled +it reads an external cluster from ``CRDB_URL`` (expected to already have both +regions added). It never fails by default — it is skipped. Mirrors the Java +``RegionalIdeaIT``. +""" + +from __future__ import annotations + +import os + +import psycopg +import pytest + +import regional_service as rs + +pytestmark = pytest.mark.skipif( + os.environ.get("CRDB_MULTIREGION") != "true", + reason="REGIONAL BY ROW needs a multi-region cluster; " + "set CRDB_MULTIREGION=true and CRDB_URL", +) + + +# tag::region-it[] +def test_writes_home_rows_in_the_pinned_region() -> None: + url = os.environ["CRDB_URL"] + with psycopg.connect(url, autocommit=True) as conn, conn.cursor() as cur: + cur.execute("DROP TABLE IF EXISTS regional_idea") + for ddl in rs.REGIONAL_BY_ROW_DDL.split(";"): + if ddl.strip(): + cur.execute(ddl) + + east = rs.add_in_us_east(url, "Home me in the east") + west = rs.add_in_us_west(url, "Home me in the west") + + assert rs.region_of(url, east) == "us-east1" + assert rs.region_of(url, west) == "us-west1" +# end::region-it[] diff --git a/examples/ideas-board/test_semantic.py b/examples/ideas-board/test_semantic.py new file mode 100644 index 0000000..46e825f --- /dev/null +++ b/examples/ideas-board/test_semantic.py @@ -0,0 +1,38 @@ +"""Fast unit test for semantic search — no Docker, no database. + +Covers the deterministic embedding provider (reproducible, right width) and the +``Document`` mapping that carries a precomputed embedding, plus the cosine +similarity ordering. Real similarity search over a VECTOR column needs a +vector-capable cluster (see ``test_semantic_it.py``). Mirrors the Java semantic +unit test. +""" + +from __future__ import annotations + +import asyncio + +from cockroachdb.ai import Document +from cockroachdb.types import DistanceMetric +from semantic_service import DIMENSIONS, DeterministicEmbeddingProvider + + +# tag::semantic-unit-test[] +def test_provider_is_deterministic_and_right_width() -> None: + provider = DeterministicEmbeddingProvider({"dark mode": [1.0, 0.0, 0.0]}) + v1 = asyncio.run(provider.embed("dark mode")) + v2 = asyncio.run(provider.embed("dark mode")) + assert v1 == v2 == [1.0, 0.0, 0.0] # mapped text is stable + assert provider.dimensions == DIMENSIONS + assert len(asyncio.run(provider.embed("unmapped"))) == DIMENSIONS # hash fallback width + + +def test_document_carries_precomputed_embedding() -> None: + doc = Document(content="Dark mode toggle", embedding=[1.0, 0.0, 0.0]) + assert doc.embedding == [1.0, 0.0, 0.0] # passed through, not regenerated + assert doc.id # auto-assigned uuid when omitted + + +def test_cosine_similarity_is_monotonic_in_distance() -> None: + cos = DistanceMetric.COSINE + assert cos.to_similarity(0.0) > cos.to_similarity(0.5) # nearer => more similar +# end::semantic-unit-test[] diff --git a/examples/ideas-board/test_semantic_it.py b/examples/ideas-board/test_semantic_it.py new file mode 100644 index 0000000..5e78132 --- /dev/null +++ b/examples/ideas-board/test_semantic_it.py @@ -0,0 +1,70 @@ +"""Integration test for semantic search — needs a VECTOR-capable CockroachDB. + +The native ``VECTOR`` type requires v25.2+; ``ensure_table()`` also issues +``CREATE VECTOR INDEX`` (v26.2+). Boots the image named by ``CRDB_VECTOR_IMAGE`` +(default ``cockroachdb/cockroach:latest-v25.2``). Skips cleanly when Docker is +unavailable, and skips honestly (rather than faking a pass) if the chosen image +lacks VECTOR support. Mirrors the Java ``SemanticSearchIT``. +""" + +from __future__ import annotations + +import asyncio +import os + +import pytest + +from cockroachdb.ai import Document +from semantic_service import DeterministicEmbeddingProvider, SemanticIdeaService + +IMAGE = os.environ.get("CRDB_VECTOR_IMAGE", "cockroachdb/cockroach:latest-v25.2") + +# Four deterministic 3-dim vectors pointing in distinct directions. +DOCS = { + "dark-mode": ("Dark mode toggle", [1.0, 0.0, 0.0]), + "mobile": ("Mobile dark theme", [0.8, 0.2, 0.0]), + "search": ("Full-text search", [0.0, 1.0, 0.0]), + "export": ("CSV export", [0.0, 0.0, 1.0]), +} +QUERY = "near dark mode" +QUERY_VEC = [0.95, 0.05, 0.0] + + +@pytest.fixture(scope="module") +def dsn() -> str: + try: + from crdb_container import insecure_crdb + except Exception as exc: # noqa: BLE001 + pytest.skip(f"testcontainers unavailable: {exc}") + try: + with insecure_crdb(image=IMAGE) as url: + yield url + except Exception as exc: # noqa: BLE001 — Docker not running / image pull failed + pytest.skip(f"Docker/CockroachDB container unavailable: {exc}") + + +def _skip_if_no_vector(exc: Exception) -> None: + if "vector" in str(exc).lower(): + pytest.skip(f"VECTOR unsupported on {IMAGE}: {exc}") + raise exc + + +# tag::semantic-it[] +def test_find_similar_returns_nearest_first(dsn: str) -> None: + provider = DeterministicEmbeddingProvider({QUERY: QUERY_VEC}) + service = SemanticIdeaService(dsn, provider) + try: + service.initialize() + except Exception as exc: # noqa: BLE001 — honest gate: skip if no VECTOR type/index + _skip_if_no_vector(exc) + + docs = [Document(id=k, content=t, embedding=v) for k, (t, v) in DOCS.items()] + asyncio.run(service.store(docs)) + + hits = asyncio.run(service.find_similar(QUERY, k=4)) + + assert [h.id for h in hits] == ["dark-mode", "mobile", "search", "export"] + distances = [h.distance for h in hits] + assert distances == sorted(distances) # closest-first + assert hits[0].distance < 0.01 # query sits almost on dark-mode +# end::semantic-it[] From 57fc9a631fe3f0150d655b2ac74addcefbd2fc97 Mon Sep 17 00:00:00 2001 From: Felipe Gutierrez Date: Thu, 19 Nov 2026 12:22:06 -0500 Subject: [PATCH 4/4] examples: satisfy ruff format + lint for CI The example/ideas-board tree never ran through CI before (first push of the branch), so ruff format --check and ruff check . flagged it. Apply ruff format to the example, auto-fix import sorting and stray noqa, and extend the examples per-file-ignores (TC, SIM105, N818) so demo code keeps a runtime pytest import and readable try/except without weakening library linting. No logic changes; unit tests still 15 passed / 5 skipped (ITs skip without Docker). --- examples/ideas-board/cdc_handler.py | 4 +--- examples/ideas-board/follower_read_service.py | 1 - examples/ideas-board/idea.py | 2 ++ examples/ideas-board/main.py | 15 ++++++++++----- examples/ideas-board/metrics_service.py | 5 +---- examples/ideas-board/regional_service.py | 4 +--- examples/ideas-board/repository.py | 2 ++ examples/ideas-board/semantic_service.py | 4 +--- examples/ideas-board/service.py | 13 ++++++------- examples/ideas-board/test_cdc.py | 3 +++ examples/ideas-board/test_concurrency.py | 9 +++++---- examples/ideas-board/test_follower_read.py | 4 +++- examples/ideas-board/test_follower_read_it.py | 7 ++++--- examples/ideas-board/test_metrics.py | 2 ++ examples/ideas-board/test_metrics_it.py | 7 ++++--- examples/ideas-board/test_regional.py | 4 +++- examples/ideas-board/test_regional_it.py | 6 +++--- examples/ideas-board/test_semantic.py | 5 ++++- examples/ideas-board/test_semantic_it.py | 10 ++++++---- examples/ideas-board/test_unit.py | 3 ++- pyproject.toml | 2 +- 21 files changed, 64 insertions(+), 48 deletions(-) diff --git a/examples/ideas-board/cdc_handler.py b/examples/ideas-board/cdc_handler.py index d10fdcd..25862e7 100644 --- a/examples/ideas-board/cdc_handler.py +++ b/examples/ideas-board/cdc_handler.py @@ -38,9 +38,7 @@ def on_change(self, event: Any) -> None: self.deletes += 1 return after = event.after - self.handled.append( - Idea(id=after["id"], text=after["text"], votes=after["votes"]) - ) + self.handled.append(Idea(id=after["id"], text=after["text"], votes=after["votes"])) # end::cdc-handler[] diff --git a/examples/ideas-board/follower_read_service.py b/examples/ideas-board/follower_read_service.py index ec0d920..7024fe3 100644 --- a/examples/ideas-board/follower_read_service.py +++ b/examples/ideas-board/follower_read_service.py @@ -12,7 +12,6 @@ from __future__ import annotations import psycopg - from idea import Idea # tag::follower-read[] diff --git a/examples/ideas-board/idea.py b/examples/ideas-board/idea.py index 2957c45..c9cad0c 100644 --- a/examples/ideas-board/idea.py +++ b/examples/ideas-board/idea.py @@ -19,4 +19,6 @@ class Idea: id: int text: str votes: int + + # end::entity[] diff --git a/examples/ideas-board/main.py b/examples/ideas-board/main.py index 1a032f8..513614c 100644 --- a/examples/ideas-board/main.py +++ b/examples/ideas-board/main.py @@ -52,7 +52,7 @@ def worker() -> None: barrier.wait() try: fn(dsn, idea_id) - except Exception as exc: # noqa: BLE001 — count, don't crash the demo + except Exception as exc: with lock: failures.append(exc) @@ -77,8 +77,10 @@ def main() -> None: failures = _hammer(dsn, idea_id, service.upvote_without_retry, votes) with conn.cursor() as cur: plain_total = repository.current_votes(cur, idea_id) - print(f"PLAIN @crdb_retry OFF : {plain_total}/{votes} votes landed " - f"({failures} lost to 40001)") + print( + f"PLAIN @crdb_retry OFF : {plain_total}/{votes} votes landed " + f"({failures} lost to 40001)" + ) # Reset, then the retry path — every vote eventually commits. with conn.cursor() as cur: @@ -86,8 +88,11 @@ def main() -> None: failures = _hammer(dsn, idea_id, service.upvote, votes) with conn.cursor() as cur: retry_total = repository.current_votes(cur, idea_id) - print(f"RETRY @crdb_retry ON : {retry_total}/{votes} votes landed " - f"({failures} failures)") + print( + f"RETRY @crdb_retry ON : {retry_total}/{votes} votes landed ({failures} failures)" + ) + + # end::runner[] diff --git a/examples/ideas-board/metrics_service.py b/examples/ideas-board/metrics_service.py index 972aec0..1424430 100644 --- a/examples/ideas-board/metrics_service.py +++ b/examples/ideas-board/metrics_service.py @@ -13,7 +13,6 @@ from typing import TYPE_CHECKING import psycopg - import repository # tag::metrics-config[] @@ -61,9 +60,7 @@ def upvote(self, idea_id: int) -> None: def _apply_upvote(self, idea_id: int) -> None: """Read current votes, add one, write it back — in one SERIALIZABLE tx.""" with psycopg.connect(self._dsn, autocommit=True) as conn: - conn.execute( - "SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL SERIALIZABLE" - ) + conn.execute("SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL SERIALIZABLE") with conn.transaction(), conn.cursor() as cur: votes = repository.current_votes(cur, idea_id) time.sleep(CONTENTION_DELAY) diff --git a/examples/ideas-board/regional_service.py b/examples/ideas-board/regional_service.py index e42379f..880e621 100644 --- a/examples/ideas-board/regional_service.py +++ b/examples/ideas-board/regional_service.py @@ -77,9 +77,7 @@ def add_in_us_west(dsn: str, text: str) -> str: def region_of(dsn: str, idea_id: str) -> str | None: """The ``crdb_region`` a row actually landed in, if present.""" with psycopg.connect(dsn, autocommit=True) as conn, conn.cursor() as cur: - cur.execute( - "SELECT crdb_region::STRING FROM regional_idea WHERE id = %s", (idea_id,) - ) + cur.execute("SELECT crdb_region::STRING FROM regional_idea WHERE id = %s", (idea_id,)) row = cur.fetchone() return row[0] if row else None diff --git a/examples/ideas-board/repository.py b/examples/ideas-board/repository.py index a3a69a2..ca772d4 100644 --- a/examples/ideas-board/repository.py +++ b/examples/ideas-board/repository.py @@ -55,4 +55,6 @@ def update_votes(cur: psycopg.Cursor, idea_id: int, votes: int) -> None: def reset(cur: psycopg.Cursor, idea_id: int, votes: int = 0) -> None: """Reset an idea's vote count (used to re-run the two paths cleanly).""" cur.execute("UPDATE ideas SET votes = %s WHERE id = %s", (votes, idea_id)) + + # end::repo[] diff --git a/examples/ideas-board/semantic_service.py b/examples/ideas-board/semantic_service.py index 8b4184e..6bb5cb5 100644 --- a/examples/ideas-board/semantic_service.py +++ b/examples/ideas-board/semantic_service.py @@ -34,9 +34,7 @@ class DeterministicEmbeddingProvider: ``dimensions``) so searches are reproducible with no external model or network. """ - def __init__( - self, mapping: dict[str, list[float]], dimensions: int = DIMENSIONS - ) -> None: + def __init__(self, mapping: dict[str, list[float]], dimensions: int = DIMENSIONS) -> None: self._mapping = mapping self._dimensions = dimensions diff --git a/examples/ideas-board/service.py b/examples/ideas-board/service.py index ca9c040..e07e4b5 100644 --- a/examples/ideas-board/service.py +++ b/examples/ideas-board/service.py @@ -11,7 +11,6 @@ import time import psycopg - import repository # tag::retry[] @@ -33,9 +32,7 @@ def _apply_upvote(dsn: str, idea_id: int) -> None: inside the retried unit — not passed in. """ with psycopg.connect(dsn, autocommit=True) as conn: - conn.execute( - "SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL SERIALIZABLE" - ) + conn.execute("SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL SERIALIZABLE") with conn.transaction(), conn.cursor() as cur: votes = repository.current_votes(cur, idea_id) time.sleep(CONTENTION_DELAY) @@ -46,13 +43,13 @@ def _apply_upvote(dsn: str, idea_id: int) -> None: def upvote_without_retry(dsn: str, idea_id: int) -> None: """Upvote with NO retry — a 40001 propagates and that vote is lost.""" with psycopg.connect(dsn, autocommit=True) as conn: - conn.execute( - "SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL SERIALIZABLE" - ) + conn.execute("SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL SERIALIZABLE") with conn.transaction(), conn.cursor() as cur: votes = repository.current_votes(cur, idea_id) new_votes = votes + 1 repository.update_votes(cur, idea_id, new_votes) + + # end::plain[] @@ -61,4 +58,6 @@ def upvote_without_retry(dsn: str, idea_id: int) -> None: def upvote(dsn: str, idea_id: int) -> None: """Upvote WITH automatic retry — every vote eventually lands.""" _apply_upvote(dsn, idea_id) + + # end::retry[] diff --git a/examples/ideas-board/test_cdc.py b/examples/ideas-board/test_cdc.py index 931b2fa..dde9c9a 100644 --- a/examples/ideas-board/test_cdc.py +++ b/examples/ideas-board/test_cdc.py @@ -12,6 +12,7 @@ import asyncio from cdc_handler import IdeaChangefeedHandler + from cockroachdb.cdc import ( ChangefeedHandlerRegistry, ChangefeedPayload, @@ -56,4 +57,6 @@ def test_registry_dispatches_webhook_to_handler() -> None: assert seen.votes == 12 assert handler.deletes == 0 assert metrics.total_events == 1 + + # end::cdc-unit-test[] diff --git a/examples/ideas-board/test_concurrency.py b/examples/ideas-board/test_concurrency.py index eca0486..5639083 100644 --- a/examples/ideas-board/test_concurrency.py +++ b/examples/ideas-board/test_concurrency.py @@ -13,7 +13,6 @@ import threading import pytest - import repository import service @@ -26,13 +25,13 @@ def dsn() -> str: try: from crdb_container import insecure_crdb - except Exception as exc: # noqa: BLE001 + except Exception as exc: pytest.skip(f"testcontainers unavailable: {exc}") try: with insecure_crdb() as url: yield url - except Exception as exc: # noqa: BLE001 — Docker not running / image pull failed + except Exception as exc: pytest.skip(f"Docker/CockroachDB container unavailable: {exc}") @@ -60,7 +59,7 @@ def worker() -> None: barrier.wait() try: fn(dsn, idea_id) - except Exception: # noqa: BLE001 — plain path drops conflicts + except Exception: pass threads = [threading.Thread(target=worker) for _ in range(THREADS)] @@ -80,4 +79,6 @@ def test_retry_lands_every_vote(dsn: str) -> None: plain_id = _seed(dsn) _run(dsn, plain_id, service.upvote_without_retry) assert _votes(dsn, plain_id) < TOTAL # plain path: conflicts lose votes + + # end::concurrency-test[] diff --git a/examples/ideas-board/test_follower_read.py b/examples/ideas-board/test_follower_read.py index 3806919..905c365 100644 --- a/examples/ideas-board/test_follower_read.py +++ b/examples/ideas-board/test_follower_read.py @@ -8,9 +8,9 @@ from __future__ import annotations +import follower_read_service as frs import pytest -import follower_read_service as frs from cockroachdb import build_staleness, follower_read from cockroachdb.core import FollowerReadContext @@ -42,4 +42,6 @@ def test_scoped_context_activates_and_resets() -> None: assert staleness == "'-5s'" assert FollowerReadContext.is_active() assert FollowerReadContext.current_staleness() is None + + # end::follower-read-unit-test[] diff --git a/examples/ideas-board/test_follower_read_it.py b/examples/ideas-board/test_follower_read_it.py index a5e8383..6602511 100644 --- a/examples/ideas-board/test_follower_read_it.py +++ b/examples/ideas-board/test_follower_read_it.py @@ -14,7 +14,6 @@ import psycopg import pytest - import repository from follower_read_service import top_ideas @@ -23,12 +22,12 @@ def dsn() -> str: try: from crdb_container import insecure_crdb - except Exception as exc: # noqa: BLE001 + except Exception as exc: pytest.skip(f"testcontainers unavailable: {exc}") try: with insecure_crdb() as url: yield url - except Exception as exc: # noqa: BLE001 — Docker not running / image pull failed + except Exception as exc: pytest.skip(f"Docker/CockroachDB container unavailable: {exc}") @@ -62,4 +61,6 @@ def test_top_ideas_from_follower_snapshot(dsn: str) -> None: assert top[0].text == "Full-text search" # highest votes sorts first assert top[0].votes == 12 assert [i.votes for i in top] == sorted((i.votes for i in top), reverse=True) + + # end::follower-read-it[] diff --git a/examples/ideas-board/test_metrics.py b/examples/ideas-board/test_metrics.py index ecbfe0a..d2e53ef 100644 --- a/examples/ideas-board/test_metrics.py +++ b/examples/ideas-board/test_metrics.py @@ -38,4 +38,6 @@ def flaky() -> str: assert metrics.total_retries == 2 # two 40001s absorbed assert metrics.transactions[TransactionOutcome.RETRIED] # retried run recorded assert metrics.total_transactions == 1 # one logical transaction + + # end::metrics-unit-test[] diff --git a/examples/ideas-board/test_metrics_it.py b/examples/ideas-board/test_metrics_it.py index a3964c6..1e9451b 100644 --- a/examples/ideas-board/test_metrics_it.py +++ b/examples/ideas-board/test_metrics_it.py @@ -13,7 +13,6 @@ import psycopg import pytest - import repository from metrics_service import MeteredIdeaService @@ -26,12 +25,12 @@ def dsn() -> str: try: from crdb_container import insecure_crdb - except Exception as exc: # noqa: BLE001 + except Exception as exc: pytest.skip(f"testcontainers unavailable: {exc}") try: with insecure_crdb() as url: yield url - except Exception as exc: # noqa: BLE001 — Docker not running / image pull failed + except Exception as exc: pytest.skip(f"Docker/CockroachDB container unavailable: {exc}") @@ -60,4 +59,6 @@ def worker() -> None: assert service.metrics.total_transactions == EXPECTED # one per metered upvote assert service.metrics.total_retries > 0 # contention forces 40001 retries + + # end::metrics-it[] diff --git a/examples/ideas-board/test_regional.py b/examples/ideas-board/test_regional.py index 8ec5692..06d2220 100644 --- a/examples/ideas-board/test_regional.py +++ b/examples/ideas-board/test_regional.py @@ -8,8 +8,8 @@ from __future__ import annotations import pytest - import regional_service as rs + from cockroachdb.core import RegionContext from cockroachdb.exceptions import RegionValidationError @@ -36,4 +36,6 @@ def test_region_validation_rejects_bad_names() -> None: RegionContext.validate("us-east1") # valid — no raise with pytest.raises(RegionValidationError): RegionContext.validate("US_EAST!") + + # end::regional-unit-test[] diff --git a/examples/ideas-board/test_regional_it.py b/examples/ideas-board/test_regional_it.py index 3b31c35..bc0caa7 100644 --- a/examples/ideas-board/test_regional_it.py +++ b/examples/ideas-board/test_regional_it.py @@ -14,13 +14,11 @@ import psycopg import pytest - import regional_service as rs pytestmark = pytest.mark.skipif( os.environ.get("CRDB_MULTIREGION") != "true", - reason="REGIONAL BY ROW needs a multi-region cluster; " - "set CRDB_MULTIREGION=true and CRDB_URL", + reason="REGIONAL BY ROW needs a multi-region cluster; set CRDB_MULTIREGION=true and CRDB_URL", ) @@ -38,4 +36,6 @@ def test_writes_home_rows_in_the_pinned_region() -> None: assert rs.region_of(url, east) == "us-east1" assert rs.region_of(url, west) == "us-west1" + + # end::region-it[] diff --git a/examples/ideas-board/test_semantic.py b/examples/ideas-board/test_semantic.py index 46e825f..234dec8 100644 --- a/examples/ideas-board/test_semantic.py +++ b/examples/ideas-board/test_semantic.py @@ -11,9 +11,10 @@ import asyncio +from semantic_service import DIMENSIONS, DeterministicEmbeddingProvider + from cockroachdb.ai import Document from cockroachdb.types import DistanceMetric -from semantic_service import DIMENSIONS, DeterministicEmbeddingProvider # tag::semantic-unit-test[] @@ -35,4 +36,6 @@ def test_document_carries_precomputed_embedding() -> None: def test_cosine_similarity_is_monotonic_in_distance() -> None: cos = DistanceMetric.COSINE assert cos.to_similarity(0.0) > cos.to_similarity(0.5) # nearer => more similar + + # end::semantic-unit-test[] diff --git a/examples/ideas-board/test_semantic_it.py b/examples/ideas-board/test_semantic_it.py index 5e78132..e3116be 100644 --- a/examples/ideas-board/test_semantic_it.py +++ b/examples/ideas-board/test_semantic_it.py @@ -13,9 +13,9 @@ import os import pytest +from semantic_service import DeterministicEmbeddingProvider, SemanticIdeaService from cockroachdb.ai import Document -from semantic_service import DeterministicEmbeddingProvider, SemanticIdeaService IMAGE = os.environ.get("CRDB_VECTOR_IMAGE", "cockroachdb/cockroach:latest-v25.2") @@ -34,12 +34,12 @@ def dsn() -> str: try: from crdb_container import insecure_crdb - except Exception as exc: # noqa: BLE001 + except Exception as exc: pytest.skip(f"testcontainers unavailable: {exc}") try: with insecure_crdb(image=IMAGE) as url: yield url - except Exception as exc: # noqa: BLE001 — Docker not running / image pull failed + except Exception as exc: pytest.skip(f"Docker/CockroachDB container unavailable: {exc}") @@ -55,7 +55,7 @@ def test_find_similar_returns_nearest_first(dsn: str) -> None: service = SemanticIdeaService(dsn, provider) try: service.initialize() - except Exception as exc: # noqa: BLE001 — honest gate: skip if no VECTOR type/index + except Exception as exc: _skip_if_no_vector(exc) docs = [Document(id=k, content=t, embedding=v) for k, (t, v) in DOCS.items()] @@ -67,4 +67,6 @@ def test_find_similar_returns_nearest_first(dsn: str) -> None: distances = [h.distance for h in hits] assert distances == sorted(distances) # closest-first assert hits[0].distance < 0.01 # query sits almost on dark-mode + + # end::semantic-it[] diff --git a/examples/ideas-board/test_unit.py b/examples/ideas-board/test_unit.py index 94e8973..ae3b885 100644 --- a/examples/ideas-board/test_unit.py +++ b/examples/ideas-board/test_unit.py @@ -9,7 +9,6 @@ import contextlib import pytest - import service @@ -66,4 +65,6 @@ def fake_connect(dsn: str, autocommit: bool = False) -> _FakeConnection: service.upvote_without_retry("postgresql://ignored", idea_id=7) assert store["written"] == 42 # read 41, wrote 41 + 1 + + # end::unit-test[] diff --git a/pyproject.toml b/pyproject.toml index 7a0e622..373ef70 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -53,7 +53,7 @@ known-first-party = ["cockroachdb"] [tool.ruff.lint.per-file-ignores] # Examples favour readability/completeness over lint purity and are not shipped. # E402: Django examples must configure settings before importing app modules. -"examples/**" = ["E402", "E501", "B904", "F401"] +"examples/**" = ["E402", "E501", "B904", "F401", "TC", "SIM105", "N818"] # Tests: names encode PostgreSQL error codes (e.g. 40P01) and fake exception # classes; these are intentional and not part of any public API. "tests/**" = ["N802", "N818", "E501", "SIM117"]