Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

7.0 KB
Raw Blame
#!/usr/bin/env python3
"""Reject FastAPI parameter markers used as Python default values.

Ruff's FAST002 intentionally focuses on decorated FastAPI routes and needs a
type annotation before it can build ``Annotated``. Reusable dependency
functions and untyped parameters can therefore retain ``= Depends(...)`` (or
another FastAPI marker) while FAST002 reports a clean tree. This hook covers
that narrow gap without importing the application or any third-party package.
"""

from __future__ import annotations

import ast
import sys
from collections.abc import Iterable, Sequence
from pathlib import Path
from typing import NamedTuple

FASTAPI_MARKERS = frozenset(
    {
        "Body",
        "Cookie",
        "Depends",
        "File",
        "Form",
        "Header",
        "Path",
        "Query",
        "Security",
    }
)
FASTAPI_MODULES = frozenset({"fastapi", "fastapi.params"})


class Diagnostic(NamedTuple):
    path: Path
    line: int
    column: int
    message: str

    def render(self) -> str:
        return f"{self.path}:{self.line}:{self.column}: {self.message}"


class _Bindings(NamedTuple):
    direct: dict[str, str]
    modules: dict[str, str]
    star_import_lines: tuple[int, ...]


def _dotted_name(node: ast.AST) -> tuple[str, ...] | None:
    parts: list[str] = []
    while isinstance(node, ast.Attribute):
        parts.append(node.attr)
        node = node.value
    if not isinstance(node, ast.Name):
        return None
    parts.append(node.id)
    return tuple(reversed(parts))


def _marker_name(node: ast.AST, bindings: _Bindings) -> str | None:
    if isinstance(node, ast.Name):
        return bindings.direct.get(node.id)

    parts = _dotted_name(node)
    if not parts or len(parts) < 2:
        return None
    module = bindings.modules.get(parts[0])
    if module is None:
        return None
    expanded = (*module.split("."), *parts[1:])
    marker = expanded[-1]
    prefix = ".".join(expanded[:-1])
    if prefix in FASTAPI_MODULES and marker in FASTAPI_MARKERS:
        return marker
    return None


def _import_bindings(tree: ast.Module) -> _Bindings:
    direct: dict[str, str] = {}
    modules: dict[str, str] = {}
    star_import_lines: list[int] = []

    for node in ast.walk(tree):
        if isinstance(node, ast.Import):
            for alias in node.names:
                if alias.name not in FASTAPI_MODULES:
                    continue
                local = alias.asname or alias.name.split(".", 1)[0]
                modules[local] = alias.name if alias.asname else "fastapi"
        elif isinstance(node, ast.ImportFrom):
            module = node.module or ""
            if module not in FASTAPI_MODULES:
                continue
            for alias in node.names:
                if alias.name == "*":
                    star_import_lines.append(node.lineno)
                elif module == "fastapi" and alias.name == "params":
                    modules[alias.asname or alias.name] = "fastapi.params"
                elif alias.name in FASTAPI_MARKERS:
                    direct[alias.asname or alias.name] = alias.name

    # Also follow simple module-level aliases such as ``Inject = Depends``.
    # Repeat to support short alias chains without attempting full data flow.
    bindings = _Bindings(direct, modules, tuple(star_import_lines))
    changed = True
    while changed:
        changed = False
        for statement in tree.body:
            if not isinstance(statement, (ast.Assign, ast.AnnAssign)):
                continue
            value = statement.value
            targets = (
                statement.targets
                if isinstance(statement, ast.Assign)
                else [statement.target]
            )
            marker = (
                _marker_name(value, bindings) if value is not None else None
            )
            if marker is None:
                continue
            for target in targets:
                if (
                    isinstance(target, ast.Name)
                    and direct.get(target.id) != marker
                ):
                    direct[target.id] = marker
                    changed = True

    return bindings


def _parameter_defaults(
    node: ast.FunctionDef | ast.AsyncFunctionDef,
) -> Iterable[tuple[ast.arg, ast.expr]]:
    positional = [*node.args.posonlyargs, *node.args.args]
    padded = [None] * (len(positional) - len(node.args.defaults))
    for argument, default in zip(
        positional, [*padded, *node.args.defaults], strict=True
    ):
        if default is not None:
            yield argument, default
    for argument, default in zip(
        node.args.kwonlyargs, node.args.kw_defaults, strict=True
    ):
        if default is not None:
            yield argument, default


def check_file(path: Path) -> tuple[Diagnostic, ...]:
    try:
        source = path.read_text(encoding="utf-8")
    except (OSError, UnicodeError) as exc:
        return (Diagnostic(path, 1, 1, f"cannot read Python source: {exc}"),)

    try:
        tree = ast.parse(source, filename=str(path))
    except SyntaxError as exc:
        return (
            Diagnostic(
                path,
                exc.lineno or 1,
                exc.offset or 1,
                "cannot verify FastAPI defaults because the file has invalid syntax",
            ),
        )

    bindings = _import_bindings(tree)
    diagnostics = [
        Diagnostic(
            path,
            line,
            1,
            "FastAPI star imports prevent reliable marker resolution; import markers explicitly",
        )
        for line in bindings.star_import_lines
    ]

    for node in ast.walk(tree):
        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
            continue
        for argument, default in _parameter_defaults(node):
            if not isinstance(default, ast.Call):
                continue
            marker = _marker_name(default.func, bindings)
            if marker is None:
                continue
            diagnostics.append(
                Diagnostic(
                    path,
                    default.lineno,
                    default.col_offset + 1,
                    f"parameter '{argument.arg}' uses {marker}(...) as a default; "
                    f"use Annotated[Type, {marker}(...)] instead",
                )
            )

    return tuple(
        sorted(
            diagnostics, key=lambda item: (item.line, item.column, item.message)
        )
    )


def check_paths(paths: Iterable[Path]) -> tuple[Diagnostic, ...]:
    diagnostics = [item for path in paths for item in check_file(path)]
    return tuple(
        sorted(
            diagnostics,
            key=lambda item: (
                str(item.path),
                item.line,
                item.column,
                item.message,
            ),
        )
    )


def main(argv: Sequence[str] | None = None) -> int:
    paths = [
        Path(value) for value in (argv if argv is not None else sys.argv[1:])
    ]
    diagnostics = check_paths(paths)
    for diagnostic in diagnostics:
        print(diagnostic.render())
    return int(bool(diagnostics))


if __name__ == "__main__":
    raise SystemExit(main())