perf: parallelize the test suite (~7x) and trim slow pre-commit hooks

.github/workflows/ci.yml

@@ -18,6 +18,8 @@ jobs:
         uses: actions/checkout@v4
       - name: Install uv
         uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
@@ -36,6 +38,8 @@ jobs:
         uses: actions/checkout@v4
       - name: Install uv
         uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
@@ -58,6 +62,8 @@ jobs:
           workspaces: rust
       - name: Install uv
         uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
@@ -67,7 +73,9 @@ jobs:
       - name: Build Rust extension
         run: uv run maturin develop --manifest-path rust/Cargo.toml
       - name: Run tests
-        run: uv run pytest
+        # `-n auto` is also set in pyproject [tool.pytest.ini_options] addopts; kept
+        # explicit here so the intent is visible. Ubuntu runners have 2-4 cores.
+        run: uv run pytest -n auto
 
   rust:
     runs-on: ubuntu-latest

.github/workflows/docs.yml

@@ -17,7 +17,7 @@ jobs:
       - name: Build documentation
         run: uv run --group dev mkdocs build --strict
       - name: Deploy to GitHub Pages
-        uses: peaceiris/actions-gh-pages@v3
+        uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./site

.pre-commit-config.yaml

@@ -1,3 +1,6 @@
+# Fast, auto-fixing checks only. Slow, whole-repo gates (pyright, the full pytest
+# suite, cargo-clippy, cargo-test) run in CI on every PR instead — running them in a
+# pre-commit hook rebuilds the Rust extension and runs the whole suite on every commit.
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.15.12
@@ -9,38 +12,10 @@ repos:
         files: ^(src|tests)/.*\.py$
   - repo: local
     hooks:
-      - id: pyright
-        name: pyright
-        entry: uv run pyright
-        language: system
-        types: [python]
-        files: ^(src|tests)/.*\.py$
-        pass_filenames: false
-      - id: pytest
-        name: pytest
-        entry: bash -c 'uv run maturin develop --manifest-path rust/Cargo.toml && uv run pytest'
-        language: system
-        types: [python]
-        files: ^(src|tests|rust)/
-        pass_filenames: false
       - id: cargo-fmt
         name: cargo-fmt
         entry: cargo fmt --check --manifest-path rust/Cargo.toml
         language: system
         types: [rust]
         files: ^rust/
         pass_filenames: false
-      - id: cargo-clippy
-        name: cargo-clippy
-        entry: cargo clippy --manifest-path rust/Cargo.toml --all-targets -- -D warnings
-        language: system
-        types: [rust]
-        files: ^rust/
-        pass_filenames: false
-      - id: cargo-test
-        name: cargo-test
-        entry: cargo test --manifest-path rust/Cargo.toml
-        language: system
-        types: [rust]
-        files: ^rust/
-        pass_filenames: false

CONTRIBUTING.md

@@ -100,13 +100,13 @@ What the gates cover:
 
 - **Ruff linting and formatting.** The current tree enforces core pycodestyle/pyflakes safety checks plus stale-suppression detection. It also enforces an expanded rule set covering common bug patterns (bugbear), simplifications, Python-version upgrades, pytest style, import order, and comprehensions. Treat `uv run ruff check .` and `uv run ruff format --check .` as the stable interface rather than relying on individual rule codes.
 - **Pyright.** Type checking runs through `uv run pyright`; the project is tightening this as a strict-inference ratchet over time.
-- **Python tests.** The suite is offline and currently runs 324 tests in roughly 40-45 seconds, reporting coverage around 94%.
+- **Python tests.** The suite is offline and runs in parallel by default via [pytest-xdist](https://pypi.org/project/pytest-xdist/) (`-n auto` in `pyproject.toml`): over 600 tests in ~20-30 seconds, reporting around 90% coverage in the default CI environment (`--extra qc`). Disable parallelism for a single serial run with `pytest -n 0`.
 - **Rust tests.** `cargo test --manifest-path rust/Cargo.toml` currently runs 46 Rust unit tests for the extension.
 - **Rust style and lints.** `cargo fmt --check` enforces formatting; clippy runs all targets with warnings denied.
 
 ## Pre-commit hooks
 
-Install hooks after setup if you want the same checks to run automatically:
+Install hooks after setup to run the fast, auto-fixing checks automatically on every commit. The slower whole-repo gates (pyright, the full pytest suite, cargo-clippy, cargo-test) are intentionally **not** pre-commit hooks — they run in CI on every pull request instead, so committing stays fast.
 
 ```bash
 uv run pre-commit install
@@ -116,11 +116,7 @@ Configured hooks:
 
 - `ruff`: fixes lint issues in `src/` and `tests/` when possible.
 - `ruff-format`: formats Python files in `src/` and `tests/`.
-- `pyright`: runs `uv run pyright` once per commit attempt.
-- `pytest`: rebuilds the extension with `uv run maturin develop --manifest-path rust/Cargo.toml`, then runs `uv run pytest`.
 - `cargo-fmt`: runs `cargo fmt --check --manifest-path rust/Cargo.toml`.
-- `cargo-clippy`: runs `cargo clippy --manifest-path rust/Cargo.toml --all-targets -- -D warnings`.
-- `cargo-test`: runs `cargo test --manifest-path rust/Cargo.toml`.
 
 ## Running subsets
 

docs/installation.md

@@ -126,7 +126,7 @@ make check
 
 The underlying stable gates are `ruff check` / `ruff format --check`, `pyright`, `pytest`, and `cargo fmt --check` / `cargo test` / `cargo clippy --all-targets -- -D warnings` (see [Development](development.md)).
 
-Install pre-commit hooks if you want the gates to run automatically before commits:
+Install pre-commit hooks to run the fast lint/format checks automatically before commits (the full gates run in CI):
 
 ```bash
 uv run pre-commit install

pyproject.toml

@@ -98,11 +98,14 @@ dev = [
     "pytest>=9.0.2",
     "pytest-cov>=7.1.0",
     "ruff>=0.15.6",
+    "pytest-xdist>=3.8.0",
 ]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
-addopts = "--cov=tablassert --cov-report=term-missing"
+# Parallel by default via pytest-xdist (~7x faster full suite, identical coverage).
+# Disable for a single serial run with `-n 0` (e.g. debugging one test).
+addopts = "--cov=tablassert --cov-report=term-missing -n auto"
 markers = ["network: requires internet"]
 
 [tool.coverage.run]