ci: add test/lint matrix and PyPI trusted-publishing workflows

ci.yml runs lint + a Python 3.12/3.13/3.14 test matrix (100% coverage gate)
plus a floor job on the lowest supported deps (FastAPI 0.115 / pydantic 2.9)
via --resolution lowest-direct, on push/PR/workflow_call. publish.yml reuses
it on release and publishes to PyPI via trusted publishing (OIDC). Version-
conditional edges are skipped on the floor; adds httpx alongside httpx2 for the
old-starlette TestClient, PyPI metadata (classifiers, URLs) and a packaging
smoke test.

Author: feodor-ra

.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v8
+        with:
+          enable-cache: true
+          python-version: "3.12"
+      - run: uv sync
+      - run: uv run ruff format --check
+      - run: uv run ruff check
+      - run: uv run ty check
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v8
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync
+      - run: uv run pytest --cov
+
+  test-floor:
+    # Lowest supported direct dependencies (FastAPI 0.115, pydantic 2.9): eager routing regime.
+    # No coverage gate — the iter_route_contexts branch cannot run without that attribute.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v8
+        with:
+          enable-cache: true
+          python-version: "3.12"
+      - run: uv sync --resolution lowest-direct
+      - run: uv run --no-sync pytest

.github/workflows/docs.yml

@@ -25,7 +25,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: astral-sh/setup-uv@v5
+      - uses: astral-sh/setup-uv@v8
         with:
           enable-cache: true
       - run: uv sync --no-dev --group docs

.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  ci:
+    uses: ./.github/workflows/ci.yml
+
+  publish:
+    needs: ci
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/fastapi-typed-errors/
+    permissions:
+      id-token: write # PyPI trusted publishing (OIDC) — no stored token
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v8
+        with:
+          python-version: "3.12"
+      - run: uv build
+      - name: Smoke test the wheel
+        run: uv run --isolated --no-project --with dist/*.whl scripts/smoke_test.py
+      - name: Smoke test the source distribution
+        run: uv run --isolated --no-project --with dist/*.tar.gz scripts/smoke_test.py
+      - run: uv publish

CLAUDE.md

@@ -94,5 +94,8 @@ src-layout, package `src/fastapi_typed_errors/`:
 - Prefer pytest **fixtures** for reusable arrange values (request objects, configured apps, built artifacts) — typed, with a docstring and a `Returns:` section. Module level is only for error classes/enums that must exist at import time (they are used in type positions). Don't name a fixture `request` — it clashes with pytest's built-in.
 - Lint everything: `just lint` (ruff format --check, ruff check, ty check). Run `uv run ruff format` to apply formatting. **ruff (preview) also formats Python code blocks inside Markdown** (`README.md`, `docs/**`), so keep doc snippets canonically formatted and re-run `just lint` after editing prose with code.
 - Docs: **Material for MkDocs**, bilingual (EN default at `/`, RU at `/ru/`) via `mkdocs-static-i18n` (folder mode: `docs/en/**`, `docs/ru/**`; `nav_translations` localize the nav; language-specific assets like the Swagger SVG live per-language, shared CSS in `docs/stylesheets/`). API reference is auto-generated from Google docstrings via `mkdocstrings[python]` (`:::` blocks). Deps in the `docs` group (`~=`); serve `just docs`, strict build `just docs-build`. Published to GitHub Pages by `.github/workflows/docs.yml` (uv build + `upload-pages-artifact`/`deploy-pages`; Pages source = "GitHub Actions").
+- CI/CD (`.github/workflows/`, uv + `astral-sh/setup-uv@v8`): `ci.yml` (on push-main / PR / `workflow_call`) — `lint` + `test` (Python matrix 3.12/3.13/3.14, `pytest --cov` → 100% gate) + `test-floor` (`uv sync --resolution lowest-direct` then **`uv run --no-sync pytest`** — `uv run` alone re-syncs to the lockfile; floor = FastAPI 0.115 / pydantic 2.9, **no** coverage gate since the `iter_route_contexts` branch can't run there). `publish.yml` (on release published) reuses `ci.yml` then publishes via **PyPI Trusted Publishing / OIDC** (`environment: pypi`, `id-token: write`, `uv build` + smoke `scripts/smoke_test.py` on wheel+sdist + `uv publish`, no token) — needs a one-time PyPI pending-publisher config.
+- Version-conditional tests: edges that behave differently on old FastAPI/pydantic (PEP 695 `type`-alias return annotations, the broken-param-hint tolerance, lazy-include dedup) are guarded by `requires_modern_fastapi = skipif(not hasattr(fastapi.routing, "iter_route_contexts"))` — they run (and count toward 100%) on the default stack, skip on the floor. `monkeypatch.delattr(..., raising=False)` where the attribute is absent on the floor.
+- Both `httpx` (old starlette `TestClient`, the FastAPI floor) and `httpx2` (new starlette) are in the dev group.
 - Environment and build: uv (`uv sync`, `uv run python ...`), build backend `uv_build`.
 - Run smoke checks against a live FastAPI app: `uv run python <script>` (`httpx2` for `TestClient` is in the dev group, so no `--with` is needed anymore).

pyproject.toml

@@ -10,6 +10,18 @@ requires-python = ">=3.12"
 license = "MIT"
 license-files = ["LICENSE"]
 keywords = ["fastapi", "errors", "openapi", "typed", "pydantic"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: FastAPI",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Internet :: WWW/HTTP",
+    "Typing :: Typed",
+]
 dependencies = [
     # 0.137/0.138 introduced the lazy _IncludedRouter tree but not the supported
     # iter_route_contexts iterator — nested includes cannot be walked there; skip that gap.
@@ -23,6 +35,12 @@ cli = ["typer>=0.15"]
 [project.scripts]
 fastapi-typed-errors = "fastapi_typed_errors.analysis.cli:main"
 
+[project.urls]
+Homepage = "https://feodor-ra.github.io/fastapi-typed-errors/"
+Documentation = "https://feodor-ra.github.io/fastapi-typed-errors/"
+Repository = "https://github.com/feodor-ra/fastapi-typed-errors"
+Issues = "https://github.com/feodor-ra/fastapi-typed-errors/issues"
+
 [build-system]
 requires = ["uv_build>=0.11.30,<0.12.0"]
 build-backend = "uv_build"
@@ -54,6 +72,11 @@ convention = "google"
     "magic-value-comparison",     # PLR2004: comparing to literal counts/exit codes is normal in tests
     "import-private-name",        # PLC2701: tests exercise the package's private internals
 ]
+"scripts/**" = [
+    "assert",                     # S101: the packaging smoke test asserts
+    "implicit-namespace-package", # INP001: scripts is not a package
+    "raw-string-in-exception",    # EM101: literal details mirror the package's own pattern
+]
 
 [tool.ty.rules]
 all = "error"
@@ -73,6 +96,8 @@ fail_under = 100
 [dependency-groups]
 dev = [
     "anyio~=4.14.2",
+    # Both TestClient transports: old starlette (fastapi floor) imports httpx, new starlette imports httpx2.
+    "httpx~=0.28.0",
     "httpx2~=2.7.0",
     "pytest~=9.1.1",
     "pytest-cov~=7.1.0",

scripts/smoke_test.py

@@ -0,0 +1,71 @@
+"""Packaging smoke test — run against the built wheel/sdist before publishing.
+
+Exercises the public API end to end (metaclass derivation, the router patch,
+OpenAPI generation and the checker) from an installed distribution, so a broken
+build or a missing ``py.typed``/module is caught before it reaches PyPI.
+"""
+
+from enum import StrEnum
+from http import HTTPStatus
+from typing import Annotated, Literal
+
+from fastapi import APIRouter, FastAPI
+from pydantic import BaseModel
+
+from fastapi_typed_errors import (
+    BaseError,
+    Raises,
+    check_raises,
+    error_models,
+    handle_base_error,
+    with_errors,
+)
+
+
+class Code(StrEnum):
+    """Smoke error codes."""
+
+    NOT_FOUND = "NOT_FOUND"
+
+
+class NotFoundError(BaseError[Literal[Code.NOT_FOUND]]):
+    """Smoke error."""
+
+    http_status = HTTPStatus.NOT_FOUND
+
+
+class Item(BaseModel):
+    """Smoke payload."""
+
+    item_id: int
+
+
+def main() -> None:
+    """Register a typed error end to end and assert the OpenAPI is typed."""
+    app = FastAPI()
+    app.add_exception_handler(BaseError, handle_base_error)
+    router = with_errors(APIRouter())
+
+    @router.get("/items/{item_id}")
+    def get_item(item_id: int) -> Annotated[Item, Raises[NotFoundError]]:
+        """Raise the typed error (a registration and analysis target).
+
+        Args:
+            item_id: Ignored.
+
+        Raises:
+            NotFoundError: Always.
+        """
+        raise NotFoundError(str(item_id))
+
+    app.include_router(router)
+
+    responses = app.openapi()["paths"]["/items/{item_id}"]["get"]["responses"]
+    assert "404" in responses
+    assert responses["200"]["content"]["application/json"]["schema"]["$ref"].endswith("Item")
+    assert error_models(NotFoundError) is NotFoundError.model
+    assert check_raises(app).ok
+
+
+if __name__ == "__main__":
+    main()

tests/analysis/test_checker.py

@@ -11,6 +11,12 @@
 
 from fastapi_typed_errors import Raises, check_raises, with_errors
 
+# The lazy include model (with per-route dedup) is FastAPI ≥ 0.139; older versions copy routes eagerly.
+requires_modern_fastapi = pytest.mark.skipif(
+    not hasattr(fastapi.routing, "iter_route_contexts"),
+    reason="requires FastAPI >= 0.139 (lazy include_router)",
+)
+
 oauth = OAuth2PasswordBearer(tokenUrl="token")
 
 
@@ -227,6 +233,7 @@ def test_websocket_route_ignored() -> None:
     assert report.checked == 1
 
 
+@requires_modern_fastapi
 def test_double_include_deduplicated() -> None:
     """A router included under two prefixes is checked once."""
     child = APIRouter()
@@ -258,7 +265,7 @@ def test_wrapped_router_still_checked() -> None:
 
 def test_fallback_without_iter_route_contexts(monkeypatch: pytest.MonkeyPatch) -> None:
     """Without ``iter_route_contexts`` a flat ``routes`` walk is used."""
-    monkeypatch.delattr(fastapi.routing, "iter_route_contexts")
+    monkeypatch.delattr(fastapi.routing, "iter_route_contexts", raising=False)
     router = APIRouter()
     router.add_api_route("/u", ep_undeclared, methods=["GET"])
 

tests/decorator/test_wrapper.py

@@ -7,6 +7,7 @@
 from typing import Annotated, Any, Literal, cast
 
 import fastapi.dependencies.utils
+import fastapi.routing
 import pytest
 from fastapi import APIRouter, Depends, FastAPI
 from fastapi.responses import Response, StreamingResponse
@@ -16,6 +17,13 @@
 
 from fastapi_typed_errors import BaseError, Raises, with_errors
 
+# FastAPI ≥ 0.139 ships iter_route_contexts and the newer pydantic that resolves PEP 695 aliases /
+# tolerates unresolvable parameter hints. Older stacks handle those edges differently upstream.
+requires_modern_fastapi = pytest.mark.skipif(
+    not hasattr(fastapi.routing, "iter_route_contexts"),
+    reason="requires FastAPI >= 0.139 (lazy routing + modern pydantic)",
+)
+
 
 class Code(StrEnum):
     """Error codes used by the test error classes."""
@@ -243,6 +251,7 @@ def endpoint() -> Annotated[None, Raises[ForbiddenError]]:
     assert "content" not in responses["204"]
 
 
+@requires_modern_fastapi
 def test_alias_return_annotation(router: APIRouter) -> None:
     """A PEP 695 ``type`` alias is unwrapped before marker extraction."""
 
@@ -253,6 +262,7 @@ def endpoint() -> AliasedItem:
     assert "404" in _responses(router, "/alias")
 
 
+@requires_modern_fastapi
 def test_alias_nested_inside_annotated(router: APIRouter) -> None:
     """Markers inside an aliased ``Annotated`` base are merged with outer ones."""
 
@@ -301,6 +311,7 @@ def endpoint() -> "MissingModel":  # ruff:ignore[undefined-name]  # ty: ignore[u
     assert responses["200"]["content"]["application/json"]["schema"]["$ref"].endswith("Item")
 
 
+@requires_modern_fastapi
 def test_unresolvable_parameter_hints_pass_through(router: APIRouter) -> None:
     """Broken parameter hints with no return annotation register exactly like on stock FastAPI."""
 
@@ -548,7 +559,7 @@ def test_auto_falls_back_without_dependency_helper(
 ) -> None:
     """If FastAPI's dependency helpers move, ``auto`` degrades to the endpoint only."""
     # Removing this name fails only our lazy import; FastAPI's routing holds its own binding.
-    monkeypatch.delattr(fastapi.dependencies.utils, "get_parameterless_sub_dependant")
+    monkeypatch.delattr(fastapi.dependencies.utils, "get_parameterless_sub_dependant", raising=False)
 
     @auto_router.get("/fallback")
     def endpoint(_: Annotated[None, Depends(raise_forbidden_dep)]) -> Item: