test(ci): stabilize CI harness, debloat test suites, and modernize tooling

.github/workflows/ci.yml

@@ -378,27 +378,60 @@ jobs:
         env:
           PYTHONFAULTHANDLER: "1"
           PYTEST_ADDOPTS: "--max-worker-restart=0"
-        # At 22min, broadcast SIGABRT to ALL python processes (controller + xdist
-        # workers). Faulthandler in each process dumps every thread to stderr
-        # before exit, so the test step log captures the actual hang site.
+        # At 22min, signal the pytest process group with SIGABRT so faulthandler
+        # dumps thread stacks to stderr, with bounded escalation to SIGTERM and SIGKILL.
+        # Background watchdog is trapped and reaped reliably on any exit.
         run: |
           set -m
-          (
-            sleep 1320
-            echo "::group::Hang detected - SIGABRT to all python"
-            pkill -ABRT -f python || true
-            sleep 10
-            echo "::endgroup::"
-          ) &
-          aborter_pid=$!
+          pytest_pgid=""
+          aborter_pid=""
+
+          cleanup() {
+            local exit_code=$?
+            trap - EXIT INT TERM
+            if [ -n "$aborter_pid" ] && kill -0 -"$aborter_pid" 2>/dev/null; then
+              kill -TERM -"$aborter_pid" 2>/dev/null || true
+              wait "$aborter_pid" 2>/dev/null || true
+            fi
+            if [ -n "$pytest_pgid" ] && kill -0 -"$pytest_pgid" 2>/dev/null; then
+              kill -TERM -"$pytest_pgid" 2>/dev/null || true
+              sleep 2
+              kill -KILL -"$pytest_pgid" 2>/dev/null || true
+            fi
+            exit "$exit_code"
+          }
+          trap cleanup EXIT
+          trap 'exit 130' INT
+          trap 'exit 143' TERM
+
           # covdefaults sets fail_under=100 globally; per-tier coverage
           # only covers a slice, so override to 0. Codecov merges the
           # tiers server-side.
-          uv run pytest tests/integration docs/examples -n 2 --dist=loadgroup \
+          uv run pytest tests/integration -n 2 --dist=loadgroup \
             --cov=sqlspec --cov-report=xml:coverage-integration.xml --cov-report=term-missing \
-            --cov-fail-under=0
+            --cov-fail-under=0 &
+          pytest_pid=$!
+          # Job control makes the background job leader its process-group leader.
+          pytest_pgid=$pytest_pid
+
+          (
+            sleep 1320
+            if kill -0 -"$pytest_pgid" 2>/dev/null; then
+              echo "::group::Hang detected after 22 minutes - SIGABRT to pytest process group $pytest_pgid"
+              kill -ABRT -"$pytest_pgid" 2>/dev/null || true
+              sleep 15
+              if kill -0 -"$pytest_pgid" 2>/dev/null; then
+                kill -TERM -"$pytest_pgid" 2>/dev/null || true
+                sleep 5
+                kill -KILL -"$pytest_pgid" 2>/dev/null || true
+              fi
+              echo "::endgroup::"
+            fi
+          ) &
+          aborter_pid=$!
+
+          wait "$pytest_pid"
           rc=$?
-          kill "$aborter_pid" 2>/dev/null || true
           exit $rc
 
       - name: Upload coverage to Codecov
@@ -427,64 +460,6 @@ jobs:
             docker logs --tail 100 "$c" 2>&1 || true
           done
 
-  # test-linux-freethreaded:
-  #   # Disabled: cp314t ecosystem not mature enough yet (missing binary wheels, long build times)
-  #   runs-on: ubuntu-latest
-  #   continue-on-error: true
-  #   timeout-minutes: 30
-  #   steps:
-  #     - uses: actions/checkout@v4
-  #     - uses: astral-sh/setup-uv@v3
-  #     - run: uv python install 3.14t
-  #     - run: uv sync --extra aiosqlite --extra duckdb --dev
-  #     - run: uv run pytest tests/unit -n 2 --dist=loadgroup
-
-  # test-windows:
-  #   runs-on: windows-latest
-  #   strategy:
-  #     fail-fast: true
-  #     matrix:
-  #       python-version: ["3.12", "3.13"]
-  #   timeout-minutes: 30
-  #   steps:
-  #     - name: Check out repository
-  #       uses: actions/checkout@v4
-
-  #     - name: Install uv
-  #       uses: astral-sh/setup-uv@v3
-
-  #     - name: Set up Python
-  #       run: uv python install ${{ matrix.python-version }}
-
-  #     - name: Install dependencies
-  #       run: uv sync --all-extras --dev
-
-  #     - name: Test
-  #       run: uv run pytest -m ""
-
-  # test-osx:
-  #   runs-on: macos-latest
-  #   strategy:
-  #     fail-fast: true
-  #     matrix:
-  #       python-version: ["3.11", "3.12", "3.13"]
-  #   timeout-minutes: 30
-  #   steps:
-  #     - name: Check out repository
-  #       uses: actions/checkout@v4
-
-  #     - name: Install uv
-  #       uses: astral-sh/setup-uv@v3
-
-  #     - name: Set up Python
-  #       run: uv python install ${{ matrix.python-version }}
-
-  #     - name: Install dependencies
-  #       run: uv sync --all-extras --dev
-
-  #     - name: Test
-  #       run: uv run pytest -m ""
-
   build-docs:
     needs:
       - ci-scope

.github/workflows/docs.yml

@@ -40,12 +40,12 @@ jobs:
         run: uv sync --all-extras --dev
 
       - name: Build documentation
-        run: uv run python tools/build_docs.py docs-build
+        run: make docs
 
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5
         with:
-          path: docs-build
+          path: docs/_build/html
 
   deploy:
     needs: build

.pre-commit-config.yaml

@@ -1,13 +1,6 @@
 default_language_version:
   python: "3"
 repos:
-  - repo: local
-    hooks:
-      - id: no-future-annotations
-        name: Disallow future annotations in package code
-        entry: python tools/hooks/no_future_annotations.py
-        language: python
-        files: ^sqlspec/.*\.py$
   - repo: https://github.com/compilerla/conventional-pre-commit
     rev: v4.4.0
     hooks:
@@ -52,10 +45,3 @@ repos:
     hooks:
       - id: sphinx-lint
         args: ["--jobs", "1"]
-  - repo: local
-    hooks:
-      - id: pypi-readme
-        name: pypi-readme
-        language: python
-        entry: python tools/pypi_readme.py
-        types: [markdown]

CONTRIBUTING.rst

@@ -34,7 +34,7 @@ Guidelines for writing code
   - All code must be fully typed (enforced via `mypy <https://mypy.readthedocs.io/en/stable/>`_ and `pyright <https://microsoft.github.io/pyright/>`_). Avoid ``Any`` whenever possible.
   - Use PEP 585 built-in collection types (``dict``, ``list``, ``tuple``, ``set``) rather than their ``typing`` module equivalents.
   - Use PEP 604 union types (``T | None``), never ``Optional[T]`` or ``Union[T, None]``.
-  - Package modules must **not** import ``from __future__ import annotations``. Prek checks this using an AST-based local hook.
+  - Package modules must **not** import ``from __future__ import annotations``. This is enforced via Ruff rule ``TID251`` (banned API).
 
 - **Comments & Documentation**:
   - **Never use in-line comments in Python code**. If code requires explanation, document the rationale in the class or function docstring.
@@ -72,8 +72,7 @@ Writing and running tests
   - Use unit tests (`tests/unit/`) for code that does not need a database (parsing, config normalization, parameter formatting).
   - Review the `test placement guide <https://github.com/litestar-org/sqlspec/blob/main/tests/README.md>`_ for detailed fixture conventions.
 - **Integration Resources**:
-  - Integration tests use ``pytest-databases`` fixtures.
-  - Run database containers locally before running integration tests if testing locally (e.g. via ``make infra-up``).
+  - Integration tests use ``pytest-databases`` fixtures to provision and manage database containers automatically.
 - **Coverage Requirements**:
   - The repository-wide coverage floor is temporarily 76%.
   - Every new commit must keep changed-code coverage at or above **90%**.

Makefile

@@ -169,7 +169,7 @@ clean:                                              ## Cleanup temporary build a
 .PHONY: test
 test:                                               ## Run the tests
 	@echo "${INFO} Running test cases... 🧪"
-	@uv run pytest -n 4 --dist=loadgroup tests/unit tests/typing docs/examples
+	@uv run pytest -n 4 --dist=loadgroup tests/unit
 	@uv run pytest -n 1 --dist=loadgroup tests/integration --ignore=tests/integration/adapters
 	@for family in $(ADAPTER_FAMILIES); do
 		uv run pytest -n 1 --dist=loadgroup "tests/integration/adapters/$${family}"
@@ -185,7 +185,7 @@ coverage:                                           ## Run tests with coverage r
 	@echo "${INFO} Running tests with coverage... 📊"
 	@uv run coverage erase
 	@uv run pytest --cov --cov-report= --cov-fail-under=0 -n 4 --dist=loadgroup --quiet \
-		tests/unit tests/typing docs/examples
+		tests/unit
 	@uv run pytest --cov --cov-append --cov-report= --cov-fail-under=0 -n 1 --dist=loadgroup --quiet \
 		tests/integration --ignore=tests/integration/adapters
 	@for family in $(ADAPTER_FAMILIES); do
@@ -259,7 +259,7 @@ lint: fix prek type-check slotscheck zizmor         ## Run all linting checks
 	@echo "${OK} All linting checks passed ✨"
 
 .PHONY: check-all
-check-all: lint test-all coverage                  ## Run all checks (lint, test, coverage)
+check-all: lint coverage                            ## Run all checks (lint, test with coverage)
 	@echo "${OK} All checks passed successfully ✨"
 
 # =============================================================================
@@ -405,49 +405,6 @@ pgo-local:                                          ## Run full three-stage PGO
 	@uv pip install dist/*.whl --force-reinstall --no-deps >/dev/null 2>&1
 	@echo "${OK} PGO build complete 🚀"
 
-# =============================================================================
-# Development Infrastructure
-# =============================================================================
-
-.PHONY: infra-up
-infra-up:                                              ## Start development infrastructure (databases, storage)
-	@echo "${INFO} Starting development infrastructure..."
-	@./tools/local-infra.sh up
-	@echo "${OK} Development infrastructure ready ✨"
-
-.PHONY: infra-down
-infra-down:                                            ## Stop development infrastructure
-	@echo "${INFO} Stopping development infrastructure..."
-	@./tools/local-infra.sh down --quiet
-	@echo "${OK} Development infrastructure stopped"
-
-.PHONY: infra-status
-infra-status:                                          ## Show development infrastructure status
-	@./tools/local-infra.sh status
-
-.PHONY: infra-cleanup
-infra-cleanup:                                         ## Clean up development infrastructure
-	@echo "${WARN} This will remove all development containers and volumes"
-	@./tools/local-infra.sh cleanup
-
-.PHONY: infra-postgres
-infra-postgres:                                        ## Start only PostgreSQL
-	@echo "${INFO} Starting PostgreSQL..."
-	@./tools/local-infra.sh up postgres --quiet
-	@echo "${OK} PostgreSQL ready on port 5433"
-
-.PHONY: infra-oracle
-infra-oracle:                                          ## Start only Oracle
-	@echo "${INFO} Starting Oracle..."
-	@./tools/local-infra.sh up oracle --quiet
-	@echo "${OK} Oracle ready on port 1522"
-
-.PHONY: infra-mysql
-infra-mysql:                                           ## Start only MySQL
-	@echo "${INFO} Starting MySQL..."
-	@./tools/local-infra.sh up mysql --quiet
-	@echo "${OK} MySQL ready on port 3307"
-
 # =============================================================================
 # End of Makefile
 # =============================================================================