Version 3 with cached cross chunk edges

.coveragerc

@@ -5,6 +5,13 @@ source = pychunkedgraph
 omit =
     *test*
     *benchmarking/*
+    pychunkedgraph/debug/*
+    pychunkedgraph/export/*
+    pychunkedgraph/jobs/*
+    pychunkedgraph/logging/*
+    pychunkedgraph/repair/*
+    pychunkedgraph/meshing/*
+    pychunkedgraph/app/*
 
 [report]
 # Regexes for lines to exclude from consideration

.dockerignore

@@ -106,6 +106,7 @@ venv.bak/
 
 # Visual Code
 .vscode/
+*.code-workspace
 
 # terraform
 .terraform/

.github/workflows/README.md

@@ -0,0 +1,51 @@
+# GitHub Actions workflows
+
+Two workflows drive CI and releases for PyChunkedGraph.
+
+| File | Workflow name | Trigger | Purpose |
+|---|---|---|---|
+| `main.yml` | PyChunkedGraph | push / PR to `main` or `pcgv3` | Build the image and run the test suite with coverage |
+| `release.yml` | publish release | manual (`workflow_dispatch`) | Bump the version, tag, and create the GitHub Release; optionally bump the Helm chart |
+
+## `main.yml` — CI
+
+Runs on every push and pull request targeting `main` or `pcgv3`. One `unit-tests` job:
+
+1. Builds the Docker image locally with Buildx (`load: true`, not pushed), tagged with the commit SHA, using the GitHub Actions layer cache.
+2. Runs `pytest` with coverage inside the container against `pychunkedgraph/tests`.
+3. Copies `coverage.xml` out and uploads it to Codecov — runs even when tests fail, and a Codecov upload error does not fail the build.
+4. Removes the test container.
+
+Secrets: `CODECOV_TOKEN`.
+
+## `release.yml` — release
+
+Manual only — dispatch it from the branch you want to release. **The branch is the major line**: `main` carries 2.x, `pcgv3` carries 3.x, because the version is a committed literal in `pychunkedgraph/_version.py` (the repo-root README has the full versioning flow). The tag and the in-code literal are written by the same job, so they never drift.
+
+### Inputs
+
+| Input | Default | Effect |
+|---|---|---|
+| `part` | `patch` | which semver component to bump — `major` / `minor` / `patch` |
+| `dry-run` | `false` | `true` computes the next version and stops: no commit, tag, release, or chart bump |
+| `skip-tests` | `false` | currently unused — no step references it |
+| `update-chart` | `false` | `true` also bumps the Helm chart `appVersion` (needs `HELM_CHART_UPDATE_TOKEN`) |
+
+### Jobs
+
+- **`bump`** — reads the version from `pychunkedgraph/_version.py`, bumps `part`, writes it back. Unless dry-run: commits `release vX.Y.Z`, tags `vX.Y.Z`, pushes the branch and the tag, then creates the GitHub Release. Needs `contents: write`.
+- **`update-chart`** — opt-in: runs only when `update-chart` is `true` (and not dry-run). Checks out `CAVEconnectome/cave-helm-charts`, sets `charts/pychunkedgraph/Chart.yaml` `appVersion` to the new version, bumps the chart's own `version` by a patch, and pushes. Needs `HELM_CHART_UPDATE_TOKEN` (write access to the chart repo).
+
+## Cutting a release
+
+```
+# preview the next version, no writes
+gh workflow run release.yml --ref pcgv3 -f part=patch -f dry-run=true
+
+# cut the release
+gh workflow run release.yml --ref pcgv3 -f part=patch
+```
+
+Or via the Actions UI: **publish release → Run workflow →** pick the branch and `part`.
+
+The pushed tag is what the image build (`cloudbuild.yaml`) builds from. New tables created by that image are stamped with this version, and the server only serves tables whose major matches. The Helm chart `appVersion` bump that rolls the image out is opt-in via `update-chart`.

.github/workflows/main.yml

@@ -4,19 +4,49 @@ on:
   push:
     branches:
       - "main"
+      - "pcgv3"
   pull_request:
     branches:
       - "main"
+      - "pcgv3"
 
 jobs:
   unit-tests:
     runs-on: ubuntu-latest
     steps:
       - name: Check out code
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
 
-      - name: Build image and run tests
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          load: true
+          tags: seunglab/pychunkedgraph:${{ github.sha }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Run tests with coverage
         run: |
-          docker build --tag seunglab/pychunkedgraph:$GITHUB_SHA .
-          docker run --rm seunglab/pychunkedgraph:$GITHUB_SHA /bin/sh -c "pytest --cov-config .coveragerc --cov=pychunkedgraph ./pychunkedgraph/tests && codecov"
+          docker run --name pcg-tests seunglab/pychunkedgraph:${{ github.sha }} \
+            /bin/sh -c "pytest --cov-config .coveragerc --cov=pychunkedgraph --cov-report=xml:/app/coverage.xml ./pychunkedgraph/tests"
+
+      - name: Copy coverage report from container
+        if: always()
+        run: docker cp pcg-tests:/app/coverage.xml ./coverage.xml
+
+      - name: Upload coverage to Codecov
+        if: always()
+        uses: codecov/codecov-action@v5
+        with:
+          files: ./coverage.xml
+          token: ${{ secrets.CODECOV_TOKEN }}
+          slug: CAVEconnectome/PyChunkedGraph
+          fail_ci_if_error: false
 
+      - name: Cleanup
+        if: always()
+        run: docker rm pcg-tests || true

.github/workflows/release.yml

@@ -20,6 +20,11 @@ on:
         type: boolean
         required: true
         default: false
+      update-chart:
+        description: "Also bump the pychunkedgraph Helm chart appVersion (needs HELM_CHART_UPDATE_TOKEN)"
+        type: boolean
+        required: false
+        default: false
 
 jobs:
   bump:
@@ -36,37 +41,34 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v4
-      - name: Get tags
-        run: git fetch --tags origin
       - name: Configure git for github-actions[bot]
         run: |
           git config --global user.name "github-actions[bot]"
           git config --global user.email "github-actions[bot]@users.noreply.github.com"
-      - name: Install Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: "3.11"
-      - name: Install bumpversion
-        run: pip install bumpversion
-      - name: Bump version with bumpversion
-        run: |
-          bumpversion ${{ github.event.inputs.part }}
-      - name: Commit and push with tags
-        if: ${{ github.event.inputs.dry-run == 'false' }}
-        run: git push --follow-tags
-      - name: Get version
+      - name: Bump version in pychunkedgraph/_version.py
         id: get-version
         run: |
-          version="$(git describe --tags)"
-          # remove the leading v from version
-          version="${version:1}"
+          cur=$(sed -n 's/^__version__ = "\(.*\)"/\1/p' pychunkedgraph/_version.py)
+          IFS=. read -r major minor patch <<< "$cur"
+          case "${{ github.event.inputs.part }}" in
+            major) major=$((major + 1)); minor=0; patch=0 ;;
+            minor) minor=$((minor + 1)); patch=0 ;;
+            patch) patch=$((patch + 1)) ;;
+          esac
+          version="$major.$minor.$patch"
+          sed -i "s/^__version__ = .*/__version__ = \"$version\"/" pychunkedgraph/_version.py
           echo "VERSION=$version" >> $GITHUB_OUTPUT
-          major_version="$(cut -d '.' -f 1 <<< $version)"
-          echo "MAJOR_VERSION=$major_version" >> $GITHUB_OUTPUT
-          minor_version="$(cut -d '.' -f 2 <<< $version)"
-          echo "MINOR_VERSION=$minor_version" >> $GITHUB_OUTPUT
-          short_version="$major_version.$minor_version"
-          echo "SHORT_VERSION=$short_version" >> $GITHUB_OUTPUT
+          echo "MAJOR_VERSION=$major" >> $GITHUB_OUTPUT
+          echo "MINOR_VERSION=$minor" >> $GITHUB_OUTPUT
+          echo "SHORT_VERSION=$major.$minor" >> $GITHUB_OUTPUT
+      - name: Commit the bump and push the tag
+        if: ${{ github.event.inputs.dry-run == 'false' }}
+        run: |
+          git add pychunkedgraph/_version.py
+          git commit -m "release v${{ steps.get-version.outputs.VERSION }}"
+          git tag "v${{ steps.get-version.outputs.VERSION }}"
+          git push origin HEAD
+          git push origin "v${{ steps.get-version.outputs.VERSION }}"
       - name: Show short version
         run: echo ${{ steps.get-version.outputs.SHORT_VERSION }}
 
@@ -92,7 +94,7 @@ jobs:
     name: Update pychunkedgraph Helm chart
     runs-on: ubuntu-latest
     needs: bump
-    if: ${{ github.event.inputs.dry-run == 'false' }}
+    if: ${{ github.event.inputs.dry-run == 'false' && github.event.inputs.update-chart == 'true' }}
     permissions:
       contents: read
       id-token: write

.gitignore

@@ -115,8 +115,11 @@ venv.bak/
 
 
 # local dev stuff
+*.code-workspace
+.claude/
 .devcontainer/
 *.ipynb
 *.rdb
 /protobuf*
-.DS_Store
+.DS_Store
+*debug.py

.pre-commit-config.yaml

@@ -0,0 +1,5 @@
+repos:
+  - repo: https://github.com/psf/black
+    rev: 26.1.0
+    hooks:
+      - id: black

Dockerfile

@@ -1,11 +1,93 @@
-FROM caveconnectome/pychunkedgraph:base_042124
+# syntax=docker/dockerfile:1
+ARG PYTHON_VERSION=3.14
+# python:X-slim is the official upstream image. Pin by digest once a
+# known-good build is identified so cache invalidation stays explicit;
+# until then, the tag follows the latest 3.14 patch release.
+ARG BASE_IMAGE=python:${PYTHON_VERSION}-slim
+
+
+######################################################
+# Stage 1: Conda environment
+######################################################
+FROM ${BASE_IMAGE} AS conda-deps
+ENV PATH="/root/miniconda3/bin:${PATH}"
+
+RUN apt-get update && apt-get install build-essential wget -y \
+  && wget -q https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh \
+  && bash Miniconda3-latest-Linux-x86_64.sh -b \
+  && rm Miniconda3-latest-Linux-x86_64.sh \
+  && conda config --add channels conda-forge \
+  && conda update -y --override-channels -c conda-forge conda \
+  && conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/main \
+  && conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/r \
+  && conda install -y --override-channels -c conda-forge conda-pack
+
+COPY requirements.yml requirements.txt requirements-dev.txt ./
+
+# Solve against baseline x86-64. conda picks microarch-optimized builds from the
+# *builder's* cpu (graph-tool ships v1/v3/v4 variants), so an image built on an
+# AVX-512 host raises SIGILL on import wherever it later lands on an older node.
+RUN --mount=type=cache,target=/opt/conda/pkgs \
+    CONDA_OVERRIDE_ARCHSPEC=x86_64 conda env create -n pcg -f requirements.yml
+
+RUN conda-pack -n pcg --ignore-missing-files -o /tmp/env.tar \
+  && mkdir -p /app/venv && cd /app/venv \
+  && tar xf /tmp/env.tar && rm /tmp/env.tar \
+  && /app/venv/bin/conda-unpack
+
+
+######################################################
+# Stage 2: Bigtable emulator
+######################################################
+FROM golang:bullseye AS bigtable-emulator
+ARG GOOGLE_CLOUD_GO_VERSION=bigtable/v1.19.0
+RUN --mount=type=cache,target=/go/pkg/mod \
+    --mount=type=cache,target=/root/.cache/go-build \
+    git clone --depth=1 --branch="$GOOGLE_CLOUD_GO_VERSION" \
+      https://github.com/googleapis/google-cloud-go.git /usr/src \
+  && cd /usr/src/bigtable && go install -v ./cmd/emulator
+
+
+######################################################
+# Stage 3: Production
+######################################################
+FROM ${BASE_IMAGE}
 ENV VIRTUAL_ENV=/app/venv
 ENV PATH="$VIRTUAL_ENV/bin:$PATH"
+# Force ld to resolve libpython3.x.so to the conda venv's copy. The
+# slim base ships its own /usr/local/lib/libpython, which the loader
+# would otherwise pair with conda-built C extensions, segfaulting in
+# PyObject_Hash during the first import.
+ENV LD_LIBRARY_PATH="$VIRTUAL_ENV/lib"
 
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      nginx supervisor redis-tools procps \
+  && (id nginx >/dev/null 2>&1 || useradd -r -d /home/nginx -s /bin/bash nginx) \
+  && mkdir -p /etc/uwsgi /home/nginx/.cloudvolume/secrets \
+  && chown -R nginx /home/nginx \
+  && rm -rf /var/lib/apt/lists/*
+
+COPY --from=conda-deps /app/venv /app/venv
+COPY --from=bigtable-emulator /go/bin/emulator /app/venv/bin/cbtemulator
 COPY override/gcloud /app/venv/bin/gcloud
 COPY override/timeout.conf /etc/nginx/conf.d/timeout.conf
+COPY override/nginx.conf /etc/nginx/nginx.conf
 COPY override/supervisord.conf /etc/supervisor/conf.d/supervisord.conf
+COPY uwsgi.ini /etc/uwsgi/uwsgi.ini
+
+# PyPI wheel bundles the zstd C source; conda-forge's system-linked
+# build lacks `multi_decompress_to_buffer`, used by io/edges.py.
+RUN pip install --no-cache-dir --no-deps --force-reinstall zstandard>=0.23.0
 
 COPY requirements.txt .
-RUN pip install --upgrade -r requirements.txt
+RUN --mount=type=cache,target=/root/.cache/pip \
+    pip install --upgrade -r requirements.txt
+
 COPY . /app
+WORKDIR /app
+
+# --no-deps: graph-tool/cloudvolume etc. are already in the venv. __version__ comes from
+# the committed pychunkedgraph/_version.py literal (bumped by the release workflow).
+RUN pip install --no-deps -e .
+
+CMD ["/usr/bin/supervisord", "-n", "-c", "/etc/supervisor/supervisord.conf"]