feat(decorator): add with_errors router patch and Raises marker

Author: feodor-ra

CLAUDE.md

@@ -6,14 +6,14 @@ Public PyPI package: typed HTTP errors for FastAPI — exact `Literal` error cod
 
 ## Status
 
-Draft. Only the `core` layer is implemented. Linters/type checker are configured (see Tooling); tests are not set up yet. Licensed under MIT (`LICENSE` + PEP 639 metadata in `pyproject.toml`).
+Draft. The `core` and `decorator` layers are implemented. Linters/type checker are configured (see Conventions); tests are not set up yet (verification via ad-hoc smoke scripts outside the repo). Licensed under MIT (`LICENSE` + PEP 639 metadata in `pyproject.toml`).
 
 ## Architecture — three independent layers
 
 Each layer is usable without the next one:
 
 1. **`core`** (done) — `BaseError`, the `BaseErrorMeta` metaclass, `ErrorResponse`, `error_models()`, `handle_base_error`.
-2. **`decorator`** (planned) — `with_errors(router)` + `Support[...]` in the return annotation (Annotated syntax). A router wrapper with a single interception point in `add_api_route`; subclassing `APIRouter` was rejected.
+2. **`decorator`** (done) — `with_errors(router)` + `Raises[...]` in the return annotation (Annotated syntax). An instance patch of `add_api_route` as the single interception point; subclassing `APIRouter` AND a wrapper object were both rejected (see decorator-layer decisions).
 3. **`analysis`** (planned) — AST walk over `raise` statements: a CI checker (declared vs actually raised) and `auto=True` (auto-populating `responses`). Study fastapi-docx before implementing.
 
 ## Layout
@@ -23,7 +23,9 @@ src-layout, package `src/fastapi_typed_errors/`:
 - `core/base.py` — `_model_title`, `ErrorResponse`, `BaseErrorMeta`, `BaseError` (hard dependency order, see the ordering convention).
 - `core/models.py` — `error_models()` with 8 `@overload`s (typeshed pattern) + catch-all.
 - `core/handlers.py` — `handle_base_error`.
-- `__init__.py` / `core/__init__.py` — public API re-exports.
+- `decorator/raises.py` — the `Raises` marker (validated at construction).
+- `decorator/wrapper.py` — `with_errors()` + the `add_api_route` patch and private helpers.
+- `__init__.py` / subpackage `__init__.py` — public API re-exports.
 - `py.typed` — the package is typed.
 
 ## Key core-layer decisions
@@ -39,14 +41,30 @@ src-layout, package `src/fastapi_typed_errors/`:
 - **No `install()`-style helpers** — the user wires everything explicitly, the FastAPI way (`app.add_exception_handler(BaseError, handle_base_error)`), same as `app.add_middleware(...)`. Starlette resolves handlers by walking `__mro__`, so the `BaseError` handler overrides the default `HTTPException` one without touching plain `HTTPException`.
 - `handle_base_error` is typed `(Request, Exception)` to match Starlette's `ExceptionHandler` contract: parameters are contravariant, so a narrower `BaseError` parameter would force a suppression onto every user's registration line (verified with ty; dropping the generic parameter does not help). Misregistration is caught at runtime instead — a non-`BaseError` argument raises a `TypeError` naming the offending type.
 - `BaseErrorMeta` is public so users can resolve metaclass conflicts (mixing `BaseError` with `ABC` etc.) via a combined metaclass, but it is deliberately NOT re-exported from any `__init__` — import from `fastapi_typed_errors.core.base`. Documented in README.
-- Rule for the future decorator layer: an explicit user `responses={}` wins over `Support` errors with the same status.
+- Rule for the future decorator layer: an explicit user `responses={}` wins over `Raises` errors with the same status.
+
+## Key decorator-layer decisions
+
+- **Instance patch, not a wrapper object** (user decision 2026-07-22, supersedes the concept doc): `with_errors[R: APIRouter](router: R, /) -> R` replaces `router.add_api_route` with a `functools.wraps` decorator on the *instance* and returns the *same* router. Reason: FastAPI 0.139's lazy `include_router` keeps the included object and `APIRouter.matches` does an **identity check** (`included_router.original_router is self`) — any duck-typed wrapper passes OpenAPI generation but silently 404s at runtime. Identity preservation makes `include_router`, websockets, app-level decorators and imperative registration work natively on every FastAPI version.
+- Single funnel: all 8 verb decorators + `api_route` + all `app.*` methods delegate into `router.add_api_route` (verified in 0.139 sources), so one patch covers everything. For an application: `with_errors(app.router)`.
+- The patch is idempotent (flag attribute `_fastapi_typed_errors_wrapped` on the replacement).
+- FastAPI's decorators pass `response_model` explicitly as a `DefaultPlaceholder` sentinel — "user set response_model" means the kwarg is present AND not a `DefaultPlaceholder`. Never inject `response_model=None` otherwise: it would disable return-annotation inference.
+- `Raises` is an inert `Annotated` metadata instance (`__class_getitem__` returns an instance; no `__get_pydantic_core_schema__`); pydantic ignores it, the 200 schema stays clean. Validation (BaseError subclass, declared code + status, non-empty) happens eagerly at `Raises[...]` evaluation, i.e. import time.
+- Normalization: `-> Annotated[Response-subclass | None, Raises[...]]` → `response_model=None` (FastAPI's `lenient_issubclass` cannot see through `Annotated`; without this the route dies with `FastAPIError` / grows a spurious `null` schema). Bare stream returns (`AsyncIterator` + Raises) are unsupported — documented limitation.
+- Merge semantics: derived entries lose to explicit per-route `responses` wholesale per status; router-level `responses` are merged by FastAPI itself and lose to per-route ones.
+- Endpoint unwrapping for annotation reading only: `functools.partial` chain → `inspect.unwrap` → callable-instance `type(obj).__call__`; the original endpoint object is always what gets registered.
+- `_find_raises` is recursive: unwraps PEP 695 `TypeAliasType`, descends into `Annotated` bases and union arms — a declared marker must never be dropped silently (adversarial review caught all three as silent-drop bugs). `_annotated_base` applies the same unwrapping for the Response/None normalization.
+- Unresolvable type hints (NameError/TypeError from `get_type_hints`): if the raw return annotation does not mention `Raises` → silent passthrough (stock FastAPI tolerates the `TYPE_CHECKING` pattern and never resolves return hints under an explicit `response_model`); if it does → fail fast with a clear `TypeError`. Never resolve stricter than stock for marker-free endpoints.
+- Follow-up idea (not implemented): PEP 692 `Unpack[TypedDict]` typing for registration kwargs.
 
 ## Conventions
 
 - This file and all code artifacts (docstrings, comments) are in English; communication with the user is in Russian.
 - Commits: Conventional Commits with English descriptions (`feat(core): ...`, `chore: ...`, `docs: ...`).
 - Member ordering, both at module level and inside classes: public first, then protected (`_name`), then private. Deviate only when definition-time dependencies force it — e.g. in `core/base.py` `_model_title` must precede `ErrorResponse` (referenced in its class body), and `ErrorResponse` -> `BaseErrorMeta` -> `BaseError` is a hard dependency chain (annotations evaluate eagerly on Python < 3.14).
 - Docstrings: **Google style** (Args/Returns/Raises/Attributes/Example).
+- Prefer PEP 695 generics (`[**P, R]`, `[R]`) over `Callable[..., Any]` in decorator/pass-through helpers; when P.kwargs must be mutated, localize the lie in a single `cast(dict[str, Any], kwargs)` alias instead of suppressions. Module-level constants are annotated `Final`.
+- Relative imports inside the package are welcome (`from ..core.base import ...`) — TID252 (`relative-imports`) is in the ignore list.
 - `Returns:` must state the return type: `type: Description` (e.g. `str | None: The declared code...`).
 - Type checker: **ty**, max strictness (`[tool.ty.rules] all = "error"`). Suppressions use ty-style comments (`# ty: ignore[rule]`); ty does not recognize mypy rule codes inside `# type: ignore[...]`.
 - Linter/formatter: **ruff** with `select = ["ALL"]` + `preview = true`, ignoring only the `TC` and `CPY` modules and `missing-trailing-comma` (COM812, formatter conflict); pydocstyle convention = google. Formatter: double quotes, `line-length = 120`. Import order: ruff isort defaults (stdlib `import` then `from` imports, third-party, local) — exactly the preferred style, no extra config needed.

README.md

@@ -2,22 +2,26 @@
 
 Typed error responses for FastAPI: `Literal` error codes in OpenAPI, discriminated `oneOf` unions, and a single source of truth — the error class itself.
 
-> **Status: draft.** Layer 1 (`core`) only; the `with_errors` decorator and AST analysis layers are coming.
+> **Status: draft.** Layers 1 (`core`) and 2 (`decorator`) are implemented; the AST analysis layer (CI checker + `auto`) is coming.
 
 ## Requirements
 
 - Python **3.12+** (PEP 695 generics)
-- FastAPI ≥ 0.115, Pydantic ≥ 2.7
+- FastAPI ≥ 0.115, Pydantic ≥ 2.9
 
 ## Quick start
 
+Declare errors once, right in the return annotation — `with_errors` fills `responses={}` for you:
+
 ```python
 from enum import StrEnum
 from http import HTTPStatus
-from typing import Literal
+from typing import Annotated, Literal
+
+from fastapi import APIRouter, FastAPI
+from pydantic import BaseModel
 
-from fastapi import FastAPI
-from fastapi_typed_errors import BaseError, error_models, handle_base_error
+from fastapi_typed_errors import BaseError, Raises, handle_base_error, with_errors
 
 
 class ErrorCode(StrEnum):
@@ -34,34 +38,63 @@ class ForbiddenError(BaseError[Literal[ErrorCode.FORBIDDEN]]):
     http_status = HTTPStatus.FORBIDDEN
 
 
+class Item(BaseModel):
+    item_id: int
+
+
 app = FastAPI()
 app.add_exception_handler(BaseError, handle_base_error)
 
+router = with_errors(APIRouter())
 
-@app.get(
-    "/items/{item_id}",
-    responses={
-        404: {"model": error_models(NotFoundError)},
-        403: {"model": error_models(ForbiddenError)},
-    },
-)
-def get_item(item_id: int) -> dict[str, int]:
+
+@router.get("/items/{item_id}")
+def get_item(item_id: int) -> Annotated[Item, Raises[NotFoundError, ForbiddenError]]:
     if item_id == 0:
         raise NotFoundError(f"No item {item_id}")
-    return {"item_id": item_id}
+    return Item(item_id=item_id)
+
+
+app.include_router(router)
 ```
 
-The response body is always:
+The error response body is always:
 
 ```json
 {"code": "NOT_FOUND", "detail": "No item 0"}
 ```
 
-and OpenAPI shows the **exact** `Literal` code per status — several errors on one status become a discriminated `oneOf` union via `error_models(A, B, ...)`.
+OpenAPI gets a `404` and a `403` entry with the **exact** `Literal` code each; several errors sharing one status become a discriminated `oneOf` union automatically. The success (`200`) schema stays clean — the `Raises` marker is invisible to pydantic.
+
+`with_errors(router)` returns the **same** `APIRouter` instance with its `add_api_route` patched on the instance, so object identity is preserved: `include_router`, websockets, imperative `add_api_route(...)` calls and app-level decorators all work natively. For an application, wrap its router: `with_errors(app.router)`.
+
+## Core layer only
+
+The decorator layer is optional sugar — `responses={}` can always be filled by hand with `error_models()`:
+
+```python
+@app.get(
+    "/items/{item_id}",
+    responses={
+        404: {"model": error_models(NotFoundError)},
+        403: {"model": error_models(ForbiddenError)},
+    },
+)
+def get_item(item_id: int) -> Item: ...
+```
 
 ## Notes
 
 - Error codes are any `StrEnum` members you bring, or plain strings: `BaseError[Literal["NOT_FOUND"]]`.
+- Wrap **before** registering: routes added to the router before `with_errors(router)` are not retrofitted.
+- An explicit `responses={<status>: ...}` on the route wins wholesale over `Raises`-derived entries for the same status. Use `int` status keys.
+- Shared error tuples work in both spellings: `Raises[*TOKEN_ERRORS]` and `Raises(*TOKEN_ERRORS)`.
+- Markers are found through PEP 695 `type` aliases, nested `Annotated` bases and union arms (`Annotated[Item, Raises[...]] | None`) — a declared `Raises` is never dropped silently.
+- Unresolvable return annotations without `Raises` (the `if TYPE_CHECKING:` import pattern) pass through untouched, exactly like stock FastAPI; with `Raises` mentioned they fail fast with a clear `TypeError`.
+- `-> Annotated[Response subclass, Raises[...]]` and `-> Annotated[None, Raises[...]]` are normalized to `response_model=None`, restoring stock FastAPI semantics for raw-response and empty routes.
+- Bare stream returns (`-> Annotated[AsyncIterator[X], Raises[...]]`, the SSE/JSONL feature) are not supported — annotate a `Response` subclass instead.
+- `Raises` metadata on a router that was **not** passed through `with_errors` is inert — nothing is injected and nothing fails (the upcoming analysis layer will catch such drift).
+- Status descriptions come from each error's `description`; several errors on one status get their descriptions joined with `;`, and the HTTP status phrase is the fallback.
 - Customize the response body by overriding `response_base` with your own generic subclass of `ErrorResponse`.
 - `BaseError` subclasses `fastapi.HTTPException`; mixing it with `ABC` and other custom-metaclass bases raises a metaclass conflict. The metaclass is public for exactly this case — build a combined one: `class Meta(BaseErrorMeta, ABCMeta): ...` (`from fastapi_typed_errors.core.base import BaseErrorMeta`; deliberately not re-exported from the package root).
 - The handler is registered explicitly — the same way you call `app.add_middleware(...)`; the package does not touch your app behind your back. `handle_base_error` is typed `(Request, Exception)` to match Starlette's handler contract, so the registration line stays clean under every type checker; registering it for a non-`BaseError` exception type fails fast with a `TypeError` at runtime.

pyproject.toml

@@ -32,6 +32,7 @@ ignore = [
     "TC",                     # flake8-type-checking: runtime type information is the point of this package
     "CPY",                    # flake8-copyright: no per-file copyright notices
     "missing-trailing-comma", # COM812: conflicts with the formatter
+    "relative-imports",       # TID252: relative imports inside the package are welcome
 ]
 
 [tool.ruff.lint.pydocstyle]

src/fastapi_typed_errors/__init__.py

@@ -10,10 +10,13 @@
     error_models,
     handle_base_error,
 )
+from .decorator import Raises, with_errors
 
 __all__ = (
     "BaseError",
     "ErrorResponse",
+    "Raises",
     "error_models",
     "handle_base_error",
+    "with_errors",
 )

src/fastapi_typed_errors/decorator/__init__.py

@@ -0,0 +1,9 @@
+"""Layer 2 — declare raisable errors in return annotations via ``with_errors`` + ``Raises``."""
+
+from .raises import Raises
+from .wrapper import with_errors
+
+__all__ = (
+    "Raises",
+    "with_errors",
+)

src/fastapi_typed_errors/decorator/raises.py

@@ -0,0 +1,78 @@
+"""The ``Raises`` marker: declares raisable errors inside a return annotation."""
+
+from typing import Any, Self, override
+
+from ..core.base import BaseError
+
+
+class Raises:
+    """Marker listing the errors a route can raise, for ``Annotated`` return metadata.
+
+    The wrapper created by ``with_errors()`` reads this marker at registration
+    time and fills the route's ``responses={}`` accordingly. The marker itself
+    is inert: pydantic and FastAPI ignore it, so the success schema stays clean.
+
+    Both spellings are equivalent; the constructor form is handy for shared
+    tuples of errors::
+
+        def get_item(item_id: int) -> Annotated[Item, Raises[NotFoundError, ForbiddenError]]: ...
+        def get_user(user_id: int) -> Annotated[User, Raises(*TOKEN_ERRORS)]: ...
+
+    Attributes:
+        errors: The declared error classes, in declaration order.
+    """
+
+    __slots__ = ("errors",)
+
+    errors: tuple[type[BaseError[Any]], ...]
+
+    def __init__(self, *errors: type[BaseError[Any]]) -> None:
+        """Validate and store the declared error classes.
+
+        Args:
+            *errors: ``BaseError`` subclasses with a declared code and status.
+
+        Raises:
+            TypeError: If no classes are given, a member is not a ``BaseError``
+                subclass, or a member lacks a declared ``error_code`` /
+                ``http_status``.
+        """
+        if not errors:
+            msg = "Raises requires at least one error class"
+            raise TypeError(msg)
+        for error in errors:
+            if not (isinstance(error, type) and issubclass(error, BaseError)):
+                msg = f"Raises accepts only BaseError subclasses, got {error!r}"
+                raise TypeError(msg)
+            try:
+                # Probe: the metaclass property raises on codeless classes, http_status may be undeclared.
+                _ = (error.error_code, error.http_status)
+            except AttributeError as exc:
+                msg = f"{error.__name__} cannot be used in Raises: {exc}"
+                raise TypeError(msg) from exc
+        self.errors = errors
+
+    def __class_getitem__(cls, errors: type[BaseError[Any]] | tuple[type[BaseError[Any]], ...]) -> Self:
+        """Build a marker instance from subscription syntax.
+
+        ``Raises[ErrA, ErrB]`` and ``Raises[*SHARED_ERRORS]`` are sugar for
+        ``Raises(ErrA, ErrB)``.
+
+        Args:
+            errors: A single error class or a tuple of them.
+
+        Returns:
+            Self: The validated marker instance.
+        """
+        items = errors if isinstance(errors, tuple) else (errors,)
+        return cls(*items)
+
+    @override
+    def __repr__(self) -> str:
+        """Render the marker as its subscription form.
+
+        Returns:
+            str: E.g. ``Raises[NotFoundError, ForbiddenError]``.
+        """
+        names = ", ".join(error.__name__ for error in self.errors)
+        return f"Raises[{names}]"