Reference: analysis

The public symbols of the analysis layer. check_raises, RaisesReport, RouteDiscrepancy come from the root; collect_raised from the analysis subpackage.

from fastapi_typed_errors import check_raises, RaisesReport, RouteDiscrepancy
from fastapi_typed_errors.analysis import collect_raised

check_raises

fastapi_typed_errors.check_raises

check_raises(
    target: FastAPI | APIRouter,
    *,
    allow_overdeclared: bool = False,
    max_depth: int = 10,
) -> RaisesReport

Check that every route's Raises declarations match the errors it can raise.

For each API route the declared set is read from the endpoint's return annotation and the raised set is collected from the endpoint plus every dependency (security schemes excluded). Discrepancies are reported in two directions: undeclared (raised but not declared) and overdeclared (declared but not found raised).

Parameters:

Name	Type	Description	Default
target	FastAPI | APIRouter	The FastAPI application or router to check.	required
allow_overdeclared	bool	When True, ignore declared-but-not-raised errors (useful for code with raises the static walker cannot see).	False
max_depth	int	How many call levels below each body to expand.	10

Returns:

Name	Type	Description
RaisesReport	RaisesReport	The discrepant routes and the number of routes checked.

RaisesReport

fastapi_typed_errors.RaisesReport dataclass

RaisesReport(
    routes: tuple[RouteDiscrepancy, ...], checked: int
)

Result of checking a whole application or router.

Attributes:

Name	Type	Description
routes	tuple[RouteDiscrepancy, ...]	The discrepant routes, in registration order.
checked	int	How many API routes were examined.

ok property

ok: bool

Whether every checked route matched its declarations.

Returns:

Name	Type	Description
bool	bool	True when there are no discrepancies.

RouteDiscrepancy

fastapi_typed_errors.RouteDiscrepancy dataclass

RouteDiscrepancy(
    path: str,
    methods: frozenset[str],
    undeclared: tuple[type[BaseError[Any]], ...],
    overdeclared: tuple[type[BaseError[Any]], ...],
)

One route whose declared errors disagree with the errors found in code.

Attributes:

Name	Type	Description
path	str	The full (prefixed) route path.
methods	frozenset[str]	The route's HTTP methods.
undeclared	tuple[type[BaseError[Any]], ...]	Errors raised in code but absent from Raises — always wrong.
overdeclared	tuple[type[BaseError[Any]], ...]	Errors declared via Raises but never found raised.

collect_raised

The AST-walking engine shared by check_raises and with_errors(auto=True).

fastapi_typed_errors.analysis.collect_raised

collect_raised(
    fn: Callable[..., Any], *, max_depth: int = 10
) -> frozenset[type[BaseError[Any]]]

Find every BaseError subclass a callable can raise, directly or via helpers.

The body is parsed with ast; raise sites and error classes passed as call arguments (the get_or_404(error=NotFoundError) pattern) are collected, and called module-level helpers are followed up to max_depth levels deep. Names are resolved against the function's globals and closure; unresolvable or unsourceable callables (builtins, C extensions, lambdas) are silently skipped.

Parameters:

Name	Type	Description	Default
fn	Callable[..., Any]	The callable to analyze (function, method, functools.partial, class or callable instance).	required
max_depth	int	How many call levels below the body to expand (0 = body only).	10

Returns:

Type	Description
frozenset[type[BaseError[Any]]]	frozenset[type[BaseError[Any]]]: The concrete error classes found.