feat: improve CI workflows and add CLAUDE.md

.github/workflows/ci.yml

@@ -1,4 +1,4 @@
-name: CI/CD
+name: CI
 
 on:
   push:
@@ -14,7 +14,6 @@ on:
 
 permissions:
   contents: read
-  id-token: write
 
 jobs:
   test:
@@ -36,9 +35,14 @@ jobs:
       - name: Install uv
         uses: astral-sh/setup-uv@v6
         with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
           version: "0.8.2"
           python-version: ${{ matrix.python-version }}
 
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
       - name: Run Tests
         run: make ci
 
@@ -61,44 +65,3 @@ jobs:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           parallel-finished: true
           carryforward: "run-ubuntu-latest-3.9,run-ubuntu-latest-3.10,run-ubuntu-latest-3.11,run-ubuntu-latest-3.12,run-ubuntu-latest-3.13"
-
-  release-please:
-    needs: test
-    if: ${{ github.ref == 'refs/heads/main' && github.event_name == 'push' && github.repository_owner == 'supabase' }}
-    runs-on: ubuntu-latest
-    name: "Bump version and create changelog"
-    permissions:
-      id-token: write # IMPORTANT: this permission is mandatory for trusted publishing
-      contents: write # needed for github actions bot to write to repo
-      pull-requests: write
-    steps:
-      - uses: googleapis/release-please-action@v4
-        id: release
-        with:
-          target-branch: ${{ github.ref_name }}
-  publish:
-    needs: release-please
-    if: ${{ startsWith(github.event.head_commit.message, 'chore(main)') && github.ref == 'refs/heads/main' && github.event_name == 'push' && github.repository_owner == 'supabase' }}
-    runs-on: ubuntu-latest
-    name: "Publish to PyPi"
-    environment:
-      name: pypi
-      url: https://pypi.org/p/supabase
-    permissions:
-      id-token: write # IMPORTANT: this permission is mandatory for trusted publishing
-      contents: write # needed for github actions bot to write to repo
-    steps:
-      - name: Clone Repository
-        uses: actions/checkout@v5
-        with:
-          ref: ${{ github.ref }}
-          fetch-depth: 0
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@v6
-        with:
-          version: "0.8.2"
-          python-version: "3.11"
-
-      - name: Build all packages and publish
-        run: make publish

.github/workflows/release.yml

@@ -0,0 +1,74 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+    paths-ignore:
+      - '.github/**'
+      - '.devcontainer/**'
+      - 'CHANGELOG.md'
+      - 'MAINTAINERS.md'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  release-please:
+    if: ${{ github.repository_owner == 'supabase' }}
+    runs-on: ubuntu-latest
+    name: "Bump version and create changelog"
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+    permissions:
+      contents: write # needed for github actions bot to write to repo
+      pull-requests: write
+    steps:
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          target-branch: ${{ github.ref_name }}
+
+  publish:
+    needs: release-please
+    if: ${{ needs.release-please.outputs.release_created == 'true' }}
+    runs-on: ubuntu-latest
+    name: "Publish to PyPI"
+    environment:
+      name: pypi
+      url: https://pypi.org/p/supabase
+    permissions:
+      id-token: write # IMPORTANT: this permission is mandatory for trusted publishing
+      contents: read
+    steps:
+      - name: Clone Repository
+        uses: actions/checkout@v5
+        with:
+          ref: ${{ needs.release-please.outputs.tag_name }}
+          fetch-depth: 0
+
+      - name: Install supabase cli latest
+        uses: supabase/setup-cli@v1
+        with:
+          version: "latest"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+          version: "0.8.2"
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Run pre-publish checks
+        run: |
+          make pre-commit
+          make ci
+
+      - name: Build all packages and publish
+        run: make publish

CLAUDE.md

@@ -0,0 +1,140 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is `supabase-py`, a Python monorepo containing all official Supabase client libraries for Python. The repository uses a workspace structure managed by `uv` with the following packages:
+
+- `supabase` - Main Supabase client library
+- `realtime` - Realtime subscriptions client
+- `supabase_functions` - Edge Functions client
+- `storage3` - Storage client
+- `postgrest` - PostgREST client
+- `supabase_auth` - Authentication client
+
+## Development Setup
+
+### Prerequisites
+- `uv` for Python project management
+- `make` for command running
+- `docker` for test containers (postgrest, auth)
+- `supabase-cli` for test containers (storage, realtime)
+
+### Environment Setup
+```bash
+# Create and activate virtual environment
+uv venv supabase-py
+source supabase-py/bin/activate
+uv sync
+```
+
+### Alternative: Nix
+If you have Nix installed, use the development shell:
+```bash
+nix develop
+```
+
+## Common Commands
+
+### Testing
+```bash
+# Run all tests for all packages
+make ci
+
+# Run tests in parallel (faster but messy output)
+make ci -j
+
+# Run tests for specific package
+make realtime.tests
+make supabase.tests
+make storage.tests
+# etc.
+```
+
+### Linting and Formatting
+```bash
+# Run pre-commit hooks (ruff lint/format, trailing whitespace, etc.)
+make pre-commit
+
+# Run type checking for specific package
+make realtime.mypy
+```
+
+### Infrastructure Management
+```bash
+# Start all test containers
+make start-infra
+
+# Stop all test containers
+make stop-infra
+```
+
+### Cleanup
+```bash
+# Clean all cache files and coverage reports
+make clean
+
+# Clean specific package
+make realtime.clean
+```
+
+### Building
+```bash
+# Build all packages
+make publish
+
+# Build specific package
+make supabase.build
+```
+
+## Architecture
+
+### Monorepo Structure
+The codebase uses a `uv` workspace with each package in `src/` having its own:
+- `pyproject.toml` - Package configuration and dependencies
+- `Makefile` - Package-specific commands
+- `README.md` - Package documentation
+
+### Async/Sync Pattern
+The `supabase` package maintains both async and sync versions:
+- `src/supabase/_async/` - Async implementations
+- `src/supabase/_sync/` - Auto-generated sync versions using `unasync`
+
+The sync versions are generated via:
+```bash
+make supabase.unasync
+make supabase.build-sync
+```
+
+### Testing Infrastructure
+- Tests require containers for services (PostgreSQL, Supabase services)
+- Each package with external dependencies has `start-infra`/`stop-infra` targets
+- Uses `pytest` with coverage reporting
+- Type checking with `mypy` where applicable
+
+### Code Quality
+- `ruff` for linting and formatting
+- `pre-commit` hooks for automated checks
+- `commitizen` for conventional commits
+- Coverage reporting with `pytest-cov`
+
+## Package-Specific Notes
+
+### Realtime
+- Requires Supabase CLI containers for testing
+- Has mypy type checking
+
+### Storage
+- Requires Supabase CLI containers for testing
+
+### Auth & PostgREST
+- Require Docker containers for testing
+
+### Functions
+- Standalone package with minimal infrastructure needs
+
+### Supabase (Main Client)
+- Aggregates all other packages
+- Has special async/sync build process
+- Most complex package with full integration tests