Distribute via PEP 503 Pages index + themed API docs

.github/workflows/ci.yml

@@ -33,5 +33,23 @@ jobs:
       - name: Mypy
         run: uv run mypy packages/cockroachdb/src packages/cockroachdb-core/src packages/cockroachdb-continuum/src packages/cockroachdb-testing/src
 
+      - name: Start CockroachDB
+        # Many tests (DDL compiler, dialect, alembic, integration) connect to a
+        # live node at localhost:26257; without one they fail with "connection
+        # refused". Testcontainers-based tests use the same Docker daemon.
+        run: |
+          docker run -d --name crdb -p 26257:26257 \
+            cockroachdb/cockroach:latest-v25.1 start-single-node --insecure
+          for i in $(seq 1 60); do
+            if docker exec crdb ./cockroach sql --insecure -e 'SELECT 1' >/dev/null 2>&1; then
+              echo "CockroachDB ready"; break
+            fi
+            sleep 2
+          done
+
       - name: Pytest
+        env:
+          CRDB_URL: postgresql://root@localhost:26257/defaultdb?sslmode=disable
+          DATABASE_URL: postgresql://root@localhost:26257/defaultdb?sslmode=disable
+          COCKROACH_URL: postgresql://root@localhost:26257/defaultdb?sslmode=disable
         run: uv run pytest tests/ -v --tb=short

.github/workflows/pages.yml

@@ -0,0 +1,56 @@
+name: Pages
+
+# Builds all workspace packages, a PEP 503 install index, and pdoc API docs,
+# then deploys them to GitHub Pages:
+#   https://cockroachlabs.github.io/cockroachdb-python-library/
+# Install packages with:
+#   pip install --extra-index-url \
+#     https://cockroachlabs.github.io/cockroachdb-python-library/simple/ cockroachdb-core
+on:
+  push:
+    branches: [main]
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+concurrency:
+  group: pages-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  pages:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v4
+
+      - name: Install Python
+        run: uv python install 3.12
+
+      - name: Sync workspace
+        run: uv sync --all-packages --all-extras
+
+      - name: Build all packages
+        run: |
+          set -euo pipefail
+          for pkg in packages/*/; do
+            echo "Building $pkg"
+            ( cd "$pkg" && uv build )
+          done
+
+      - name: Generate API docs (pdoc)
+        run: uv run --with pdoc pdoc cockroachdb -o _site/apidocs
+
+      - name: Assemble Pages site (landing + PEP 503 index)
+        run: python3 scripts/build_pages.py
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: _site
+          publish_branch: gh-pages

README.md

@@ -1,11 +1,11 @@
 # CockroachDB Python Library
 
-[![PyPI](https://img.shields.io/pypi/v/cockroachdb.svg)](https://pypi.org/project/cockroachdb/)
-[![Python](https://img.shields.io/pypi/pyversions/cockroachdb.svg)](https://pypi.org/project/cockroachdb/)
-[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
-[![CI](https://img.shields.io/github/actions/workflow/status/cockroachdb/cockroachdb-python-library/ci.yml?branch=main)](https://github.com/cockroachdb/cockroachdb-python-library/actions)
+[![CI](https://github.com/cockroachlabs/cockroachdb-python-library/actions/workflows/ci.yml/badge.svg)](https://github.com/cockroachlabs/cockroachdb-python-library/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/v/release/cockroachlabs/cockroachdb-python-library?sort=semver)](https://github.com/cockroachlabs/cockroachdb-python-library/releases)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
 
-A production-grade Python library for [CockroachDB](https://www.cockroachlabs.com/) that provides automatic transaction retry handling, multi-region support, follower reads, CDC webhook handlers, vector search, and RAG pipelines. Part of the CockroachDB language-specific library family alongside the [Java Spring Boot Starter](https://github.com/cockroachdb/cockroachdb-java-library), [.NET Library](https://github.com/cockroachdb/cockroachdb-dotnet-library), and [Go Library](https://github.com/cockroachdb/cockroachdb-go-library).
+A production-grade Python library for [CockroachDB](https://www.cockroachlabs.com/) that provides automatic transaction retry handling, multi-region support, follower reads, CDC webhook handlers, vector search, and RAG pipelines. Part of the CockroachDB language-specific library family alongside the [Java Spring Boot Starter](https://github.com/cockroachlabs/cockroachdb-java-library), [.NET Library](https://github.com/cockroachlabs/cockroachdb-dotnet-library), and [Go Library](https://github.com/cockroachlabs/cockroachdb-go-library).
 
 ## Architecture
 
@@ -21,6 +21,10 @@ The library is structured as a layered monorepo of six packages with a clear dep
 
 ## Quick Install
 
+> Packages are published to this repository's GitHub Pages index (not PyPI).
+> Add `--extra-index-url https://cockroachlabs.github.io/cockroachdb-python-library/simple/`
+> to each `pip install` below, or set it once in your `pip.conf`.
+
 ```bash
 # Base package (decorators, types, config, exceptions)
 pip install cockroachdb
@@ -482,9 +486,16 @@ Optional surfaces for [Cockroach Continuum](https://www.cockroachlabs.com/docs/c
 
 ```python
 from cockroachdb.continuum import (
-    CloudConfig, make_cloud, datadog_export, health,
-    VirtualClusterManager, routing_conn_string,
-    McpConfig, make_mcp, McpAegisClient, McpToolNames,
+    CloudConfig,
+    make_cloud,
+    datadog_export,
+    health,
+    VirtualClusterManager,
+    routing_conn_string,
+    McpConfig,
+    make_mcp,
+    McpAegisClient,
+    McpToolNames,
 )
 
 # --- Cloud control plane (simulated until api_key is set) ---
@@ -494,14 +505,16 @@ cloud.configure_metric_export(cluster_id, datadog_export(dd_key, "US1"))  # type
 ready = health(cloud)  # bool
 
 # --- Virtual clusters + routing ---
-vm = VirtualClusterManager(conn)      # any DB-API connection (e.g. psycopg)
+vm = VirtualClusterManager(conn)  # any DB-API connection (e.g. psycopg)
 vm.create("analytics")
 dsn = routing_conn_string(base_dsn, "analytics")  # adds -ccluster option
 
 # --- MCP client (real 2025-06-18 wire protocol) + Aegis over MCP ---
 mcp = make_mcp(McpConfig(enabled=True, endpoint="https://cockroachlabs.cloud/mcp", token=key))
 tools = mcp.list_tools()
-aegis = McpAegisClient(mcp, McpToolNames(findings="list_findings"))  # discover names via list_tools
+aegis = McpAegisClient(
+    mcp, McpToolNames(findings="list_findings")
+)  # discover names via list_tools
 findings = aegis.findings()
 ```
 
@@ -511,7 +524,12 @@ Also in the `continuum` package: a standalone **Aegis** client (findings/recomme
 
 ```python
 from cockroachdb.continuum import (
-    AegisConfig, make_aegis, AegisExhaust, storage_summary, vcluster, Priority,
+    AegisConfig,
+    make_aegis,
+    AegisExhaust,
+    storage_summary,
+    vcluster,
+    Priority,
 )
 
 # Aegis — simulated until an endpoint is set:

packages/cockroachdb-continuum/src/cockroachdb/continuum/mcp.py

@@ -17,19 +17,20 @@
 import json
 import urllib.error
 import urllib.request
+from collections.abc import Callable, Mapping
 from dataclasses import dataclass, field
 from itertools import count
 from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
 
 if TYPE_CHECKING:
-    from collections.abc import Mapping
+    from typing import TypeAlias
 
 PROTOCOL_VERSION = "2025-06-18"
 
 # A transport maps (method, url, headers, body) -> (status, response_headers, text).
-McpTransport = (
-    "Callable[[str, str, Mapping[str, str], str | None], tuple[int, Mapping[str, str], str]]"
-)
+McpTransport: TypeAlias = Callable[
+    [str, str, Mapping[str, str], str | None], tuple[int, Mapping[str, str], str]
+]
 
 
 @dataclass(frozen=True)

packages/cockroachdb-continuum/tests/test_cloud.py

@@ -54,8 +54,18 @@ def __call__(self, method, url, headers, body):
 
 def test_http_list_parses_and_sends_bearer():
     body = json.dumps(
-        {"clusters": [{"id": "c1", "name": "prod", "plan": "STANDARD",
-                       "state": "CREATED", "cloud_provider": "AWS", "regions": ["us-east-1"]}]}
+        {
+            "clusters": [
+                {
+                    "id": "c1",
+                    "name": "prod",
+                    "plan": "STANDARD",
+                    "state": "CREATED",
+                    "cloud_provider": "AWS",
+                    "regions": ["us-east-1"],
+                }
+            ]
+        }
     )
     t = _RecordingTransport({("GET", "/clusters"): (200, body)})
     c = HttpCloudClient(CloudConfig(enabled=True, api_key="sk-123"), transport=t)

pyproject.toml

@@ -57,6 +57,8 @@ known-first-party = ["cockroachdb"]
 # 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"]
+# scripts: build helpers with embedded HTML/CSS template strings (long lines).
+"scripts/**" = ["E501"]
 
 [tool.mypy]
 python_version = "3.11"